DC Hub — Data Center & Power Intelligence

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

Annotations already indicate readOnlyHint=true, so no contradiction. The description adds valuable behavioral context ('Refreshed Fridays 14:00 UTC') and implies no side effects, enhancing transparency 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 purpose, followed by return fields and usage guidelines. It is slightly lengthy but well-structured with no redundant information; each sentence adds 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?

No output schema, but the description lists return fields (facility_count, etc.), and usage guidelines are provided. Both parameters are documented in schema. For a read-only index tool, this is fairly complete, though it could mention pagination if applicable.

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 (limit, horizon) fully described in the input schema. The description does not add additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: ranking data center markets by deployable AI capacity within specific timeframes, listing return fields, and explicitly distinguishing from sibling tools like rank_markets and grid_transition_radar.

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

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

Provides explicit use cases (AI capex planning, GPU cluster siting, hyperscaler deal forecasting) and explicit exclusions with alternative tool names, giving clear guidance on when to use this tool versus others.

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 the description confirms read-only behavior. It adds important details: the representative_point is centroid of largest member (not geometric center) to avoid off-parcel points, and returns a handoff for chaining. 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 economically written with no filler: one sentence for purpose, one for returns, one for usage guidance, and one caveat. Front-loaded with the main action and key return fields.

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

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

Given the tool's moderate complexity (2 params, 1 required, no output schema), the description fully covers purpose, parameters, return values, usage context, and caveats. It integrates well with sibling tool names and context signals.

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

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

Schema coverage is 100%, but description adds significant value: for geometry, it explains the format with example and clarifies MultiPolygon as one envelope. For capacity_mw, it describes its role in the site_evaluation_handoff. This goes beyond basic schema 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 specifies the verb ('Structured read'), resource ('parcel BOUNDARY'), and return values (geodesic total_acres, per-member breakdown, contiguous flag, representative_point, site_evaluation_handoff). It distinguishes from siblings by explicitly naming alternatives: analyze_site for lat/lon and get_refined_queue for queue survivors.

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

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

The description states when to use ('when you HAVE a boundary') and when not to, providing concrete alternative tools. It also notes a limitation (DC Hub does not own parcel-boundary dataset) that affects when results auto-carry geometry.

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, so the description carries less burden. It adds value by listing the comprehensive return fields and noting that state improves tax-incentive lookup, but doesn't disclose any additional behavioral traits beyond what's implied by 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 front-loaded with the primary use case and example, then lists parameters and returns. It is structured well and each sentence serves a purpose, though it is somewhat lengthy.

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 lack of an output schema, the description thoroughly enumerates return fields. It covers all relevant inputs and outputs, making the tool's behavior fully understandable without additional documentation.

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

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

Schema coverage is 100%, but the description adds context: example values, typical capacity range, and state's role in tax lookup. This elevates understanding beyond the schema alone, though it doesn't explain every parameter in extreme detail.

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

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

The description explicitly states the tool's purpose: analyzing one lat/lon for data-center suitability. It provides a concrete example and distinguishes from siblings like compare_sites and find_alternatives, making the purpose crystal 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?

It clearly states when to use (single site analysis) and explicitly warns against using for comparing multiple sites or finding sites, naming the appropriate alternative tools. This is exemplary guidance for an AI agent.

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

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

Annotations declare non-read-only (readOnlyHint=false) and non-destructive (destructiveHint=false), but the description adds rich behavioral context: it explains the purpose (recoverability, receipts), consent requirements, opt-in marketing behavior, default transactional only, and what happens on failure (key keeps working). 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 thorough but slightly verbose; however, it is front-loaded with the primary purpose and every sentence contributes critical information. It could be streamlined without losing content, but remains effective.

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 no output schema, the description explains the return value ('unlocked benefits + confirmation'). For 3 parameters with 100% schema coverage and no nested objects, the description covers all aspects: purpose, usage, constraints, consent, and failure behavior, making it fully complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with detailed descriptions, but the description adds substantial value beyond the schema: for email it warns against placeholders; for api_key it clarifies omission binds active key; for marketing_opt_in it stresses explicit human agreement and default false. This fully compensates for any schema limitations.

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 ties a DC Hub key to a human's email for recoverability and upgrade receipts. It specifies it is optional and not gated, and distinguishes from sibling tools like recover_my_key or subscribe_digest by explicitly mentioning its unique function.

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 (once human shares email), when-not-to-use (if email not shared, ask first), and what to avoid (never invent or guess email). It also explains consequences (fake email makes key unrecoverable) and alternatives (if email fails, try another address).

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 provide readOnlyHint=false and destructiveHint=false. Description adds extensive behavioral context: free tier limitations, daily calls, depth, recoverability via email, and upgrade path. 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?

Description is front-loaded with purpose and usage. While lengthy, every sentence adds useful information. Could be slightly more concise, but structure is logical and 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?

No output schema, but description lists return fields. Explains free tier details and recovery. Doesn't cover error cases, but for a key-claiming tool it is fairly complete. Mentions related tools.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds value by explaining why email is useful (recoverable across sessions) and that client_name is for attribution. Goes beyond 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?

Clearly states it mints a free DC Hub dev key instantly. Differentiates from siblings by specifying when to use (paywall or 1-result preview) and mentions complementary tool unlock_more_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?

Explicitly says 'Call this the moment you hit a paywall or a 1-result preview'. Mentions alternative unlock_more_data for more calls. No explicit when-not-to-use, but context is 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?

Discloses read-only nature (consistent with readOnlyHint), specifies input constraints (2-4 ISOs, valid list), and fully describes the return structure, providing 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?

Four well-organized sentences: purpose, example, parameter details, return structure, and exclusions. Front-loaded and no unnecessary 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?

With one simple parameter and no output schema, the description fully covers all needed information: input constraints, return fields, and usage boundaries. No 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% and includes valid values and format; the tool description adds an example but little new information beyond what the schema already provides.

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

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

The description clearly states the tool compares 2-4 ISO grids side-by-side for metrics like fuel mix, demand, and queue depth, and distinguishes it from siblings like get_grid_intelligence and 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?

Explicitly says when to use ('instead of N sequential get_grid_intelligence calls') and when not to ('Do NOT use to rank ALL grids globally' or for single-ISO deep brief), naming alternative tools.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds behavioral context by detailing the return structure (sites with scores, winner, decision_rationale) and typical use case, going beyond annotations. No contradictions.

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

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

The description is well-structured with a clear purpose statement, example, parameter details, output format, and usage notes. It is front-loaded with the core function. Slightly longer than necessary but each part adds value.

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

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

Given no output schema, the description provides a detailed return structure (sites list with attributes, winner, decision_rationale). It includes a comprehensive example and covers all essential context for an agent to use the tool correctly, even with no nested objects.

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 covers both parameters with descriptions (100% coverage). The description adds valuable context: explains the semicolon-separated format, imposes a 2-4 limit on locations, and gives a typical capacity range (50-500 MW), which the schema lacks.

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 tool compares 2-4 candidate parcels side-by-side for winner selection, listing specific attributes (grid headroom, fiber, water, etc.) and includes an example. It clearly distinguishes from siblings like analyze_site and rank_markets.

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

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

The description explicitly says when to use ('when a user has narrowed to 2-4 candidate parcels and wants a side-by-side winner picker') and when not to use ('Do NOT use for a single site...use analyze_site or to rank entire markets...use rank_markets').

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

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

Beyond readOnlyHint annotation, it discloses behavioral traits: paid key required for full autopsy, progressive disclosure to manage cost, and pricing implications of different comparables levels. 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 concise and well-structured: one sentence for purpose, one for return fields, one for progressive disclosure, and an example call. No fluff or redundant 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 no output schema, the description adequately explains return values (deals with buyer, seller, value, market, DCPI verdict, time-to-power, and optional per-deal autopsy). It also covers comparables levels. The tool's behavior is fully described.

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 description adds value: explains default limit ~15, comparables default 'none' as cheapest, and recommends escalation only for drilling into deals. This provides context 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 purpose: tracking data-center M&A deal flow with DCPI verdict overlay. It specifies return fields (buyer, seller, value, market) and the per-deal autopsy read. This distinguishes it from sibling tools like 'hyperscaler_deals' or 'list_transactions' which focus on other aspects.

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 usage guidance via progressive disclosure: default comparables='none' (cheapest), escalate to 'summary' or 'full' for deals being drilled into. It also suggests trying limit=15. However, it does not explicitly mention when not to use this tool or compare to alternatives.

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

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

Annotations declare readOnlyHint=true, and the description adds valuable context: it returns tool families with when-to-use notes, is a navigation layer, and is not exhaustive. This fully discloses its behavior and limitations beyond the annotations.

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

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

The description is concise with two sentences, front-loaded with the key purpose ('Meta-tool: navigate...'). Every sentence adds value without redundancy.

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

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

For a meta-tool with 1 optional parameter and no output schema, the description is fully complete: it explains what is returned (families with when-to-use notes and flagship tools), how to use it (first then call chosen tool), and its relation to tools/list.

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 'query' parameter has a descriptive example in the schema. The description mentions filtering but adds no new meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'navigate' and resource 'tool families', distinguishing it from sibling tools by being a meta-tool for discovery. It explicitly says 'instead of scanning the whole list', making its purpose distinct.

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 guidance: 'Call this FIRST when you are unsure which tool fits a task; then call the chosen tool'. It also mentions optional query filtering and notes that tools/list is canonical, offering clear when-to-use context.

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

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

Annotations already mark this as readOnlyHint=true, so the description's extra detail about returning file contents as text and listing included fields (DCPI score, target MW, etc.) adds valuable context 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 three focused sentences plus a param note, with no wasted words. It front-loads purpose and usage, then efficiently covers parameters and return 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?

For a simple export tool with one optional parameter and no output schema, the description fully covers purpose, usage, parameters, return format, and data content. No gaps remain.

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

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

With 100% schema coverage, the baseline is 3. The description enhances parameter meaning by explaining what each format yields (CSV rows vs. GeoJSON FeatureCollection) and mentions data fields, which is more informative than the schema's brief description.

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

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

The description explicitly states the tool's purpose: exporting a user's saved shortlist for offline use. It provides a concrete example ('Export my saved sites as GeoJSON for QGIS') and distinguishes itself from sibling tools list_saved_sites and save_site, making the purpose unmistakable.

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

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

The description includes clear when-to-use and when-not-to-use guidance, naming the exact alternatives (list_saved_sites, save_site) and framing export_dataset as the 'bulk-download path'. This eliminates ambiguity for the agent.

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

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

Annotations declare readOnlyHint=true, and description adds that it returns a public summary with specific fields, reinforcing read-only behavior and providing 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?

Two sentences, front-loaded with core purpose and efficient secondary sentence for return format and alternatives, no extraneous 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?

Despite no output schema, description explicitly lists returned fields and their meaning, covers the tool's role in workflow (post-search), and mentions alternatives, making it fully complete.

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

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

Schema covers the single parameter fully, and description adds a concrete example and clarifies it comes from prior search results, adding meaningful context.

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

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

The description clearly states the tool fetches a DC Hub record for an ID from the search tool, and specifies the returned resource and format, distinguishing it from siblings like get_facility.

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 (after obtaining id from search) and when to use alternatives (get_facility or open url for full specs), providing clear 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 discloses the return structure (ranked alternatives with similarity_score, match_reasons, and key_differences) and mentions key parameters. Annotations indicate readOnlyHint=true, and the description does not contradict this; it implies a read operation by returning options.

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

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

The description is well-structured, starting with the use case, followed by an example, parameter summary, return description, and a clear 'do not use' section. While it is somewhat lengthy, each sentence adds value, and the key 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?

Given the tool has 5 parameters and no output schema, the description covers purpose, usage, parameter details, and return structure sufficiently for an AI agent to understand when and how to use it. It lacks details on pagination or exact scoring format, but these are optional for basic use.

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 5 parameters. The description adds value by explaining that facility_id or name can be used (though schema only has facility_id) and mentions capacity_mw which is not in schema. It clarifies required fields despite schema not marking any as required, providing useful context 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: find similar nearby options to a specific facility. It distinguishes itself from siblings like score_facility, analyze_site, and compare_sites by specifying it discovers candidates from a single seed facility, not for scoring or head-to-head comparison.

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 (user likes one specific facility and wants similar alternatives) and provides an example. It also explicitly states when NOT to use: not for scoring one site (use score_facility or analyze_site) or comparing 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?

Discloses all key behaviors: returns a survey with verdict and fields, provides a temporary download link valid ~7 days with no login. Annotations indicate readOnlyHint true, which aligns with the read-only nature of generating a report.

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

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

Well-structured with use case, example, param list, return description, and alternative. Reasonably concise given the complexity, but slightly verbose in the param explanations (e.g., repeating min/max ranges already in schema).

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

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

Given 7 parameters and no output schema, the description thoroughly explains inputs (with examples) and outputs (survey fields and PDF URL behavior). Also addresses the alternative tool for simpler use, making it complete for agent understanding.

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

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

Adds significant value beyond schema descriptions: examples, required status for lat/lon (though schema doesn't enforce), default for prepared_by, and optional nature of latency_target with default. However, the discrepancy between description saying lat/lon required and schema not requiring them is a minor inconsistency.

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 generates a shareable, branded multi-page Site Analysis PDF for a single lat/lon, explicitly differentiating it from analyze_site which returns a numeric score. The example and param list solidify the purpose.

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

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

Explicitly states when to use ('Use when a user wants a SHAREABLE, branded multi-page Site Analysis PDF… the polished client deliverable') and when not to use ('For just the numeric suitability score, use analyze_site instead'). Provides clear 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 declare readOnlyHint=true, and the description reinforces this by stating it's a curated ecosystem index, not live telemetry. 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?

Three sentences, front-loaded with the core purpose, followed by clarifying notes and alternative tool usage. No fluff.

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

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

For a zero-parameter tool with no output schema, the description fully explains what it returns (roster with platforms, frameworks, tools, authentication tiers) and its limitations (not live).

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?

No parameters exist in the input schema, so the description naturally cannot add parameter meaning. Baseline 4 applies as schema coverage is 100% and there are no parameters to document.

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

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

The description clearly defines the tool as a curated roster of AI platforms and agent frameworks, specifying its content and distinguishing it from live telemetry. It uses a specific verb ('see') and resource ('platforms DC Hub supports'), and differentiates from sibling get_backup_status.

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 it to see which platforms DC Hub supports and how to connect them.' Also provides a negative case: 'Do NOT use for platform uptime / backup health (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, so the safety profile is clear. The description adds value by detailing the specific metrics returned (db backup, freshness colors, heartbeat score, etc.) and clarifying this is platform/infra health, not content. 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?

Two sentences: the first efficiently lists all metrics, the second provides usage guidance and differentiation. No unnecessary words; every sentence earns its place.

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

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

For a tool with no parameters and no output schema, the description covers all relevant aspects: what metrics are returned, usage context, and what not to use it for. It is complete and informative.

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 description coverage is 100%. The description does not need to add parameter semantics, but it does not detract. Baseline for zero params is 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 returns platform health metrics including database backup status, data freshness, agentic heartbeat, MCP call volume, and DCPI cadence. It distinguishes itself from sibling tools by explicitly saying not to use for specific dataset freshness, recommending get_changes 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 provides explicit guidance on when to use ('trust/uptime signals before relying on the platform in production') and when not to use ('Do NOT use for the freshness of a specific dataset'), along with a specific alternative tool (get_changes).

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

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

Annotations declare readOnlyHint=true, and the description aligns with a safe read operation. The description adds behavioral context beyond annotations by explaining that the tool returns specific data types (DCPI movers, facilities, deals, news) and that caching and reusing 'generated_at' is expected. 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 a single paragraph that front-loads the core purpose ('Incremental sync') and then efficiently covers usage, parameters, and return data. It is slightly verbose but every sentence adds value; no redundant content.

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

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

Given no output schema, the description fully explains the return values ('DCPI 7-day market movers, newly discovered facilities, new M&A deals + news') and the usage pattern (caching and reusing 'generated_at'). This provides a complete mental model for the agent to use the tool effectively.

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 both parameters. The description adds significant value by explaining the 'since' parameter with concrete examples ('24h', '7d') and stating the default (24h), which goes beyond the schema's generic description. The 'limit' parameter is correctly noted as optional.

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 as an incremental sync mechanism ('Incremental sync — what changed in DC Hub since a timestamp'), using a specific verb ('sync') and resource ('changes'). It distinguishes itself from sibling 'get_' tools that fetch full datasets by emphasizing delta-only updates.

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 guidance on when to use the tool (to pull the delta instead of refetching everything) and how to use it (pass 'since' parameter with ISO-8601 or shorthand, cache 'generated_at', pass it back next call). It lacks explicit exclusions or alternatives but is sufficient for an agent to determine appropriate 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 show readOnlyHint=true. Description adds behavioral detail: it consolidates multiple tool calls into one and specifies output structure (top_markets, candidate_facilities, etc.).

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 front-loaded with purpose, gives example, param details, output format, and exclusions. Slightly dense but efficient; could be more concise but still effective.

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 no output schema, description fully explains output fields. It also covers usage, input, and constraints, making it complete for a tool replacing multiple others.

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 one free-text param. Description adds an example ('100MW AI training campus in Texas') and explains what to include (MW, geography, workload, deadline, constraints).

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 is for open-ended siting questions and returns a ready-to-quote answer. It distinguishes from siblings like analyze_site and rank_markets.

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

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

Explicitly states when to use (open-ended siting question) and when not to use (for single lat/lon or one-criterion ranking), with alternative tools named.

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

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

The description adds value beyond the readOnlyHint annotation by describing the nature of the data returned (live pricing, attribution to DC Hub). It does not mention any destructive behavior, which is consistent with the annotation. However, it could have mentioned rate limits or freshness of data, but overall it provides sufficient 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 a single paragraph but packs a lot of useful information front-loaded. Every sentence earns its place, though it could be slightly more structured (e.g., bullet points) for readability. No redundancy.

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

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

Given the tool's complexity (3 parameters, no output schema), the description covers purpose, usage, return fields, and alternatives thoroughly. It compensates for the lack of output schema by listing return fields. All necessary contextual information for an agent to correctly invoke the tool is present.

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

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

Schema coverage is 100%, so baseline is 3. The description adds clarification that iso is 'required' and lists valid values, though the schema does not mark iso as required (possible inconsistency). No additional semantics provided for state or data_type beyond the schema. The description adds marginal value over the schema.

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

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

The description clearly states the tool is for live energy pricing for 7 US ISOs, listing specific data returned (retail rate, wholesale/LMP, natural gas price, grid status). It distinguishes from siblings by explicitly naming alternative tools for related but different queries (get_grid_data, get_grid_intelligence, get_gas_economics).

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

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

Provides explicit when-to-use guidance ('Use when a user asks...') with a concrete example. Also specifies when NOT to use the tool, listing three alternative sibling tools for different use cases, making it clear when to choose another tool.

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

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

Annotations already declare readOnlyHint=true, so the description need not restate that. It adds value by detailing what information is returned (full metadata including many specific fields), which goes beyond the annotation. No contradiction, and no mention of destructive behavior.

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

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

The description is fairly concise given the amount of information it conveys. It front-loads the purpose and then lists fields. Slightly longer than necessary but effective.

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?

There is no output schema, so the description reasonably handles explaining return values by listing many fields (name, operator, address, power capacity, cooling type, fiber providers, etc.). It also explains the optional include_power and include_nearby parameters. For a single-facility lookup tool, this is comprehensive.

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

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

Schema coverage is 100%, so the schema already describes all parameters. The description adds some value by providing example calls and clarifying the purpose of id/name/slug, but it does not significantly add meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it returns full metadata for one facility, listing multiple fields (name, operator, address, lat/lon, power capacity, etc.). It distinguishes from the sibling tool search_facilities by explicitly saying not to use it for searching or listing 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 gives explicit usage examples ('Try: get_facility id=equinix-dc1-ashburn — or get_facility slug=digital-realty-iad8') and warns against using it for search or listing, directing to search_facilities 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 provide readOnlyHint; the description adds return format (GeoJSON FeatureCollection) with detailed properties, example usage, and constraints on market filtering (~1.2° radius). No contradictions. Could mention any performance limitations but still strong.

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 a single focused paragraph with front-loaded purpose, inline example, parameter guidance, and a clear 'Do NOT use' section. Every sentence serves a purpose without redundancy.

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

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

Given 4 parameters (none required), no output schema, and rich annotations, the description fully covers what the tool does, how to use it, and what it returns. Includes alternatives and exclusions, making it self-contained for an AI agent.

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

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

Schema coverage is 100% (baseline 3). The description adds value by listing allowed carrier values, explaining route_type options, detailing market behavior with radius, and providing a usage example. Slight improvement over schema alone.

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

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

The description clearly states the tool retrieves fiber intelligence for site scoring, route mapping, and dark-fiber assessment. It distinguishes from siblings by explicitly saying not to use for single-facility counting (get_facility) or interconnection scores (analyze_site).

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 scenarios and alternatives. Gives a concrete example with parameter values. Clearly states when not to use the tool and which sibling to use instead.

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

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

Annotations declare readOnlyHint=true, and the description aligns by describing a query operation. The description adds value beyond annotations by detailing the return fields (e.g., near_net_bucket, single_carrier_risk) and explaining the verdict logic. 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 a single paragraph that efficiently covers use case, example, parameters, return structure, and exclusions. It is well-structured and front-loaded with the purpose, but slightly longer than necessary due to repeating 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?

Given the tool has no output schema, the description fully compensates by listing all return fields with types and values (score 0-100, near_net_bucket options, etc.). It also covers when not to use and alternatives, making it complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, with the input schema already providing clear descriptions for all three parameters (lat, lon, radius_km including default and range). The description reiterates this information without adding significant new meaning, so baseline 3 is appropriate.

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

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

The description clearly states the tool provides a fiber-readiness/connectivity verdict for a single parcel/site using lat/lon. It distinguishes itself from siblings by explicitly stating not to use for carrier routes (use get_fiber_intel) or full site suitability (use analyze_site).

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

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

The description explicitly says 'Use when you need the FIBER-READINESS / connectivity verdict for ONE parcel or site' and provides an example query. It also lists what not to use it for and names alternative tools, giving comprehensive 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, and the description reinforces this by describing the tool as returning data. It adds detail about the return structure and custom heat rate behavior. However, it doesn't disclose potential data freshness or API call effects beyond the 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 dense yet concise, front-loading the core purpose and then methodically listing outputs and usage constraints. No superfluous sentences; every clause adds value.

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

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

Given no output schema, the description effectively enumerates the return fields. It also mentions related tools. A minor gap: it doesn't specify default heat rates when the parameter is omitted, but the schema indicates it's optional.

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

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

Schema coverage is 100% with clear descriptions. The description adds meaning by noting that market slugs come from rank_markets/get_market_dcpi_rank and that heat_rate_btu_per_kwh is for a custom scenario, going 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 computes 'Behind-the-meter / gas-fired power ECONOMICS for a US data-center market' and lists specific components (Henry Hub spot, basis differential, delivered tariffs, levelized cost). It distinguishes from siblings like get_gas_index and get_grid_data by explicitly saying what not to use it for.

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 tells when to use it ('the number a BTM developer compares against a grid PPA') and explicitly states when not to use it ('Do NOT use for the electricity grid fuel mix... or the per-state gas suitability score'), including alternatives. It also mentions pairing with get_gas_index.

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

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

Beyond the readOnlyHint annotation, the description details the output: per-state breakdown including composite DCGI, sub-scores, pipeline count, operators, verdict. It also notes attribution requirements (CC-BY-4.0). No annotation 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 moderately concise, front-loading the core purpose. Every sentence adds value, but it could be slightly trimmed (e.g., the note about attribution could be moved to a separate section). Still, it is well-structured and avoids redundancy.

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

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

With no output schema, the description fully explains the return values: composite score, sub-scores, infrastructure counts, verdict. It covers both single-state and national modes. The context of being an authoritative answer with attribution is included, making it complete for agent understanding.

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% description coverage, so baseline is 3. The description adds meaning by explaining that omitting 'state' returns a national ranking and that 'limit' applies there. It also provides a concrete example ('get_gas_index state=TX'), improving usability.

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

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

The description explicitly states the tool returns the Data Center Gas Index (DCGI), a per-state natural-gas suitability score. It distinguishes from sibling tools by naming the specific domain (gas suitability) and contrasts with electricity or live pricing tools, making its purpose unmistakable.

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

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

The description provides clear when-to-use guidance: for gas-fired data center power suitability scoring. It explicitly states when NOT to use (for electricity grid or live pricing) and suggests alternative tools (get_grid_data, get_grid_intelligence, get_energy_prices). Also includes a usage 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?

Annotations already declare readOnlyHint=true, so the read-only nature is established. The description goes further by explicitly listing omitted data categories (gas storage, LNG, firm pipeline capacity) and stating that null values are 'never fabricated'—adding trustworthy context beyond structured fields.

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

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

The description is front-loaded with the most critical information (purpose and usage) and is thorough without being wasteful. It is longer than average, but every sentence earns its place; the density is appropriate for the complexity of the 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 no output schema, the description fully documents the return structure: every field, their data types, what they represent, and the presence of data_basis labels. It also explicitly states what is intentionally omitted, providing complete context for an agent to interpret the 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%, and the description essentially repeats the schema's parameter descriptions ('US state code or name') without adding new semantic detail. It mentions 'region' but the schema includes both 'state' and 'region'; the description doesn't clarify their relationship or precedence, so it adds no 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 use case (human asks about gas-fired power economics for a data center in a US state) and provides concrete examples. It explicitly distinguishes from two sibling tools: get_grid_intelligence and 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?

The description states exactly when to use this tool and when not to, naming alternative tools: 'Do NOT use for electricity grid headroom (use get_grid_intelligence) or the DCGI score alone (use get_gas_index).' It also frames it as the 'GAS analogue of get_grid_intelligence.'

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

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

Annotations include readOnlyHint: true, so the agent knows it's a read operation. The description adds that it is 'Raw real-time telemetry' from EIA hourly RTO, providing behavioral context beyond annotations. No contradictions.

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

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

The description is a single, information-dense sentence with no wasted words. It front-loads the core purpose and immediately provides usage constraints, making it efficient for an AI agent to parse.

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

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

The description covers the data scope and constraints well. However, since there is no output schema, it could optionally mention the return format (e.g., raw JSON). As it stands, it provides enough context for an agent to understand what data to expect (fuel mix, demand, curves).

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 parameters are well-documented. The description adds value by giving examples ('pass iso=PJM') and linking parameters to data (fuel_mix, demand, demand_curve). However, it doesn't elaborate on all parameters beyond the schema, but the high coverage makes this less critical.

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 provides real-time electricity grid data (fuel mix, demand, 24h demand curve) for 7 US ISOs via EIA hourly RTO. It distinguishes from siblings by specifying what not to use for: power-availability, time-to-power, interconnection-queue analysis (use get_grid_intelligence), retail/gas pricing (use get_energy_prices), and non-US grids (use get_grid_scoreboard).

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

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

Explicitly states when to use (for one ISO real-time telemetry) and when not to use, naming alternatives: get_grid_intelligence, get_energy_prices, get_grid_scoreboard. Provides clear context for selection.

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

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

Annotations already declare readOnlyHint=true, so the description's disclosure of return fields and behavior for balancing authorities adds valuable context beyond the annotation, without contradiction.

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

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

The description is dense but well-structured, front-loading the purpose and example. Every sentence is informative, though slightly lengthy due to comprehensive field listing.

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 (multiple regions, many return fields, no output schema), the description fully explains inputs, outputs, and edge cases, making it a complete guide for correct invocation.

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

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

Schema coverage is 100%, but the description adds value by explaining aliases, listing valid values, and detailing behavioral differences for balancing authorities versus ISOs.

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: answering power availability and timeline queries for a single ISO, with a concrete example. It distinguishes from sibling tools like compare_isos and 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?

Explicitly states when to use (single ISO query) and when not (comparing ISOs or global ranking). Names alternatives (compare_isos, get_grid_scoreboard) and provides detailed parameter aliases.

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. The description adds behavioral context: data sources, the unranked treatment of Australia, and attribution requirements. This extends 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 and lists many regions and sources, which may hinder quick reading. It is well-structured with front-loaded purpose, but could be more concise.

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

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

For a parameterless tool with no output schema, the description covers return data, ranking logic, data sources, caveats, and attribution. It is fully self-contained.

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

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

There are zero parameters, so baseline is 4. The description adds no parameter info because none are needed.

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

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

The description explicitly states the tool provides a live global grid scoreboard ranking grids by renewable share, fuel mix, and demand. It names specific operators and regions, and distinguishes from siblings like compare_isos and get_grid_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?

The description gives clear context for when to use this tool (global ranking for data center siting) and explicitly contrasts with siblings. However, it does not explicitly state when not to use it.

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

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

Annotations declare readOnlyHint=true, and the description adds behavioral context: returns raw assets with distance and capacity, joined to HIFLD/EIA. Does not contradict annotations, but lacks details on rate limits or authentication.

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, well-structured paragraph that front-loads the purpose. It is concise with no fluff, though slightly more structured formatting (e.g., bullet points) could improve readability.

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

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

Given the complexity (multiple asset types, optional layer, no output schema), the description adequately explains what is returned but lacks details on return structure, pagination, or error handling. The missing output schema reduces completeness.

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

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

Schema coverage is 100%, so parameter descriptions are already detailed in the schema. The description adds marginal value by explaining the output format (distance + capacity) and providing an example call, but does not significantly enhance parameter understanding.

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

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

The description clearly states the tool returns nearby infrastructure for a location, listing specific asset types (substations, transmission lines, pipelines, power plants). It differentiates from the sibling tool 'analyze_site' by explicitly saying not to use it for a single scored site-suitability verdict.

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

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

Provides explicit when to use (for raw nearby assets) and when not to use (use analyze_site for scored verdict). Includes a usage example with parameters, guiding the agent on correct invocation.

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?

Describes the return format: index value, percentile rank, 7d/30d trend, and component scores. Annotations already indicate readOnlyHint=true, so the description adds significant behavioral context about the output structure beyond what annotations provide.

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

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

Very concise: three sentences, front-loaded with purpose, then output details, then usage guidance. 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?

Despite lacking output schema, the description fully covers return values and usage constraints. For a zero-parameter read-only tool, this is complete and leaves no ambiguity.

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?

No parameters to describe. Schema coverage is 100% (zero params). Baseline 4 for zero parameters is appropriate. Description does not need to add parameter info.

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 a real-time composite market health score (0-100) aggregating multiple factors. It distinguishes itself from sibling tools like get_market_intel and rank_markets by specifying its unique output and 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?

Explicitly states when to use (to get ONE composite health number for a market) and when not (do NOT use for full metric set or ranking). Provides alternative tool names (get_market_intel, rank_markets) for excluded cases.

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 indicate readOnlyHint: true, and the description adds behavioral context: the tool returns data from public queues, explains the special ERCOT large-load numbers (with provenance), and why other ISOs' data_center_gw is null. No contradictions.

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

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

The description is dense and informative but relatively long. Each sentence adds value, but it could be more concise. However, it is well-structured with clear use and non-use cases.

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

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

With no output schema, the description adequately covers return fields (queued_load_total_gw, queued_load_data_center_gw, top_subregions, provenance) and limitations. It provides sufficient context for an agent to understand what data to 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?

Schema coverage is 100% for the single parameter 'iso'. The description adds value by specifying that omitting iso returns an all-ISO snapshot, listing the 7 ISOs, and explaining the ERCOT-specific behavior, all beyond the schema description.

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

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

The description explicitly states the tool returns an ISO interconnection queue snapshot of total queued generation capacity per ISO, and distinguishes it from sibling tools like get_grid_intelligence and grid_transition_radar by specifying its scope and purpose.

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

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

The description provides clear usage guidance: use for queue-depth site-selection and AI/data-center-load saturation intel, and explicitly says not to use for single-site time-to-power or forward-looking emergence, naming alternative tools.

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

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

Annotations include readOnlyHint=true. The description adds behavioral context beyond annotations: token-budgeted sections filled in priority order, each with token count, as_of, and cite URL. 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?

Description is lengthy but well-structured, front-loaded with main purpose, then details, example, and exclusions. Every sentence adds value; minor redundancy could be trimmed.

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

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

Given no output schema, description details return format and fields (sections, used_tokens, omitted). Covers purpose, parameters, behavior, and exclusions. No crucial missing information.

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

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

Schema coverage is 100% for both parameters. Description adds meaning: lists required ISO values, max_tokens range and default, and explains greedy filling behavior under budget.

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

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

The description clearly states the tool provides a token-budgeted context pack for a US ISO/RTO, with specific verb 'briefing' and content sections. It distinguishes from siblings by naming alternatives like get_grid_data, get_grid_intelligence, compare_isos, and 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?

Explicitly states when to use: when a whole-grid briefing is needed. Provides clear exclusions and alternatives, e.g., 'Do NOT use for raw single-ISO telemetry (use get_grid_data)...'

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 annotation, description details token-budgeted greedy filling, priority order, and return structure (sections with tokens, as_of, cite). 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?

Description is dense but well-organized with front-loaded purpose, example, param details, and exclusions. Slightly verbose but every sentence adds 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?

Despite no output schema, description fully specifies return format (sections, used_tokens, omitted) and token-count pricing, making it self-sufficient.

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

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

With 100% schema coverage, description adds value by explaining market slug source (rank_markets) and how max_tokens controls section inclusion in priority order.

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 explicitly states 'Use when an agent needs a WHOLE-market briefing' and differentiates from siblings like get_market_dcpi_rank, get_market_intel, and rank_markets.

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

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

Provides clear when-to-use guidance with example and explicitly lists what not to use it for (single metric, raw metrics, cross-market ranking), naming alternatives.

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

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

Annotations already declare readOnlyHint=true, so the description does not need to repeat safety. It adds value by detailing the output fields (verdict, composite_score, narrative) and notes the attribution requirement, which aids in proper usage beyond the 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 structured with a clear lead sentence, then field enumeration, usage guidance, and exclusion statements. It is slightly verbose but every sentence adds value; minimal fat remains.

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 absence of an output schema, the description compensates by listing all output fields and the narrative block behavior. Combined with annotations and single parameter, the description provides everything needed to invoke the tool correctly.

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

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

Schema coverage is 100% with a single parameter 'market_slug' that already includes examples and source guidance. The description adds no further parameter semantics, so a baseline score of 3 applies.

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

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

The description clearly states the tool provides a DCPI rank for a single market, including a BUILD/CAUTION/AVOID verdict and numeric scores. It explicitly distinguishes from sibling tools 'rank_markets' and 'compare_isos', ensuring no ambiguity about scope.

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

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

The description gives explicit guidance: 'Use to answer "should I build here?"' and provides clear exclusions with alternatives ('Do NOT use to rank many markets at once (use rank_markets) or to compare ISO grids (use compare_isos)').

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 mark readOnlyHint=true, and the description adds full behavioral context: returns a JSON object with specific fields like capacity, vacancy, pricing, operators, and DCPI verdict. 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 a single paragraph but well-structured, front-loading the core purpose and constraints. It uses about 6 sentences, which is efficient but not overly concise; still clear and scannable.

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

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

Given the tool's 4 parameters and no output schema, the description fully explains the return fields and provides usage examples and constraints, making it complete for agent understanding.

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 value by explaining the 'market' parameter with examples and emphasizing its slug format. It does not detail optional parameters 'metric', 'period', 'compare_to', but the schema already describes them.

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 specifies the exact purpose: retrieving data for a single data-center market, including metrics like vacancy, pricing, and growth. It clearly distinguishes from sibling tools like rank_markets and get_facility.

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 when a user asks about ONE data-center market') and when not to use ('Do NOT use to rank multiple markets...or for a single facility'), providing alternatives. An example query with parameter usage is included.

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?

Consistent with readOnlyHint annotation. Discloses data source (DC Hub, CC-BY-4.0) and describes return formats in detail.

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

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

Well-structured with example and front-loaded purpose, but slightly verbose with repeated output details; could be tightened.

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?

Fully covers all aspects for a simple 1-param read-only tool: both invocation modes, output fields, valid inputs, data source, and disclaimers.

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 100%, but description adds rich context: explains optionality, both invocation modes (with/without market), valid values, and output structure per mode.

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?

Clearly states it retrieves metro-level fiber depth profiles (carrier count, route miles, etc.) and explicitly distinguishes from sibling tools like get_fiber_readiness and get_fiber_intel.

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?

Specifies when to use (user asks for deepest fiber, metro profile) and when not to use (parcel-level verdict, route geometry), with examples and alternative tool names.

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 readOnlyHint=true; description adds update frequency (refreshed every 30 min) and source scope. 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?

Single dense paragraph that front-loads purpose, then provides details in logical order. Could be slightly more concise, but 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?

Covers what the tool returns, how often it updates, filtering options, example, and exclusions. No output schema needed given the clear return 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?

Schema covers all 7 parameters with descriptions (100% coverage), so description adds limited value beyond that. Example usage is helpful but not essential.

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?

Immediately states it provides curated data center industry news from 40+ sources, lists the types of information returned, and distinguishes from sibling tools like list_transactions and get_pipeline.

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 (industry news) and when not to use (structured M&A deals, construction pipeline), names alternatives, and provides a usage 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?

Annotations include readOnlyHint=true, which the description does not contradict. The description adds context about dataset size (540+ projects, 369 GW) and indicates the tool is read-only. It explains the return format and parameter usage.

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 well-structured with front-loaded purpose, example, parameter details, return format, and exclusions. Every sentence adds value, but it is slightly verbose.

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 there is no output schema, the description fully covers return format and all necessary context. It addresses usage, parameters, return data, and sibling tool distinctions, making it complete for a complex 7-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?

Schema description coverage is 100%, providing baseline of 3. The description adds meaningful examples and specific usage for each parameter (e.g., status one of 'announced'|'permitted', operator like 'Equinix', country as ISO-2 code). Also explains pagination with limit/offset.

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

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

Description clearly states the tool retrieves forward-looking construction pipeline data (540+ projects, 369 GW). It specifies the resource ('construction pipeline') and the verb ('get'), and distinguishes from sibling tools like search_facilities and list_transactions.

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 provides when to use (user asks about what is being built/announced/permitted) and when not to (use search_facilities for operational, list_transactions for M&A). Includes an example query with parameters.

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

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

Annotations already state readOnlyHint=true. The description adds valuable behavioral context beyond this, including the data source (EIA-860M, nationwide including non-ISO regions), the output structure (summary with total MW, mix by technology+status, plus largest projects), and details on location and status fields. It does not contradict 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 concisely structured with all sentences earning their place. It starts with usage context, describes the data, lists filterable parameters, provides an example, and then explicates exclusions. No redundant or irrelevant 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 absence of an output schema, the description sufficiently details the return value (summary: total planned MW, mix by technology and status, largest projects) and the per-generator fields (location, state, county, balancing authority, technology/fuel, nameplate MW, status, planned online month/year). It covers all expected information for an agent to use the tool correctly.

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

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

Input schema coverage is 100%, so baseline is 3. The description adds extra semantics by explaining the meaning of status codes (P/L/T=planned, U/V=under construction, TS=testing) and that min_mw refers to nameplate capacity. This adds moderate value beyond the schema.

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

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

The description clearly states the tool returns the forward supply pipeline of new power generation projects. It specifies the resource ('WHERE NEW POWER GENERATION is coming online') and distinguishes from multiple sibling tools by explicitly saying when not to use it (e.g., for already-operating capacity use get_grid_intelligence/get_grid_data, for data-center construction use get_pipeline).

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 ('Use when a user asks WHERE NEW POWER GENERATION is coming online') and when-not-to-use instructions with alternative tool names. It also includes an example query ('Try: get_power_pipeline state=VA'), giving clear guidance for correct invocation.

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. The description adds extensive behavioral details: server-side reduction, return entity structure, spatial predicate behavior, and hard cut for max_ttp_months. No contradiction with annotations.

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

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

Well-structured with front-loaded purpose, but somewhat verbose with multiple paragraphs and secondary details like 'Phase 2 LIVE'. Most sentences add value, but could be tightened.

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

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

Comprehensive for a complex tool with 9 parameters and no output schema. Covers return structure, example query, sibling distinctions, and even how to pipe output into analyze_site.

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, but the description adds significant value beyond schema: explains substring matching for fuel_type, dataset limitations for max_fiber_km, and the hard cut behavior for max_ttp_months with examples.

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

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

The description clearly states the tool performs 'server-side SET-REDUCTION over the US ISO interconnection queue', filtering projects by multiple criteria. It distinguishes itself from sibling tools like get_interconnection_queue and analyze_site by specifying when to use each.

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 ('high-cardinality siting/arbitrage scans') and when not to use ('do NOT use for the ISO-level GW aggregate (use get_interconnection_queue) or a single-site read (use analyze_site)'). Also provides a concrete example query.

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

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

Annotations already declare readOnlyHint=true. The description goes beyond by detailing what the tool returns (capacity, capacity factor, top projects, RPS target, source) and the data source ('EIA-860 + state RPS'). 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 moderately detailed but efficient. It includes an example, parameter guidance, and return format. While it lists return fields inline (increasing length), it saves space by avoiding repetition and is well-structured.

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

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

Given that there is no output schema and 4 parameters, the description fully covers: purpose, usage examples, parameter semantics, return values, data source, and exclusions. No gaps remain for an agent to use the tool correctly.

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

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

The input schema covers 100% of parameters, and the description adds meaning: clarifies enum values for energy_type ('solar', 'wind', 'combined'), states the format for state ('2-letter US code'), and explains the optional lat/lon ('find nearest projects within 50mi'). This 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 clearly states the tool's purpose: retrieving renewable energy data for a US state to support data center siting, PPA sizing, or RE100/24-7-CFE feasibility. It uses specific verbs ('siting', 'sizing', 'assessing') and distinguishes from sibling tools like get_grid_data and 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?

Provides explicit usage guidance: 'Do NOT use for live grid generation (use get_grid_data) or non-US (use get_grid_scoreboard)'. Also includes a concrete example ('What is Texas wind+solar capacity...') showing how to invoke the tool with parameters.

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?

While readOnlyHint=true is annotated, the description adds value by detailing the re-scoring behavior and the returned fields (saved_score, current_score, score_delta_since_saved). 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 concise (3 sentences) with clear front-loading of purpose. Every sentence adds information, though minor redundancy (e.g., 'scoped to your API key') is acceptable.

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 no output schema, the description adequately explains parameters and return values. It could mention error handling or prerequisites, but the behavior for a retrieval tool is sufficiently covered.

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 enhances the refresh parameter by explaining its default and the re-scoring effect, plus the output fields. This adds meaning beyond the schema 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 retrieves a saved shortlist (Phase 5) with a specific behavior (re-scoring with refresh=true). It distinguishes from sibling tools by emphasizing the drift tracking for siting campaigns.

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 a clear use case ('maintain a siting campaign across days/weeks') and contrasts refresh=true vs false. However, it lacks explicit when-not-to-use or alternative tool mentions (e.g., list_saved_sites for listing all shortlists).

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 include readOnlyHint=true, consistent with description. Description adds return structure (state, programs array with fields), citation requirements, and scope (covers only tax factor for one US state). 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 informative and well-structured, front-loading the use case and example. Slightly verbose but each sentence adds 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?

For a single-parameter tool with no output schema, the description provides detailed return structure, usage context, and attribution requirements. Complete enough for correct 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% for the single parameter 'state'. The description reinforces it as a required 2-letter US code and shows usage in example, adding clarity 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: retrieving data-center tax-incentive packages by US state. It uses a specific verb ('get') and resource ('tax incentives') and distinguishes from siblings like analyze_site and rank_markets.

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

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

Provides explicit when-to-use (user asks about tax breaks for a state) and when-not-to-use (not for combined site analysis or market ranking). Includes an example query and parameter specification.

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

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

Annotations already provide readOnlyHint=true, indicating no side effects. The description adds context about the tool's data sources ('Joined to USGS water-stress + US Drought Monitor') and pricing ('Free tier'), which is beyond what annotations offer. 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 well-structured, starting with the primary purpose, then usage guidelines, then parameter explanation, and finally return value structure. While slightly verbose, every sentence contributes value. It is front-loaded with the key usage context.

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 no output schema, the description details the returned fields (water_stress_score, drought_category, outlook_12mo, cooling_water_assessment, source) and data provenance. For a tool with 3 non-nested parameters, this provides sufficient context for an agent to invoke it correctly 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?

The input schema has 100% coverage with detailed descriptions for each parameter. The description adds further meaning by explaining the mutual exclusivity ('ONE of lat+lon, state, or county') and prioritizing precision ('lat/lon gives the most precise read'). This enhances the schema's 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 purpose: 'scoring a US site for cooling-water sustainability'. It uses specific verb ('score') and resource ('US site for cooling-water sustainability'). It explicitly distinguishes itself from sibling tools like get_infrastructure and analyze_site, making the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance ('Use when scoring a US site for cooling-water sustainability') and when-not-to-use guidance ('Do NOT use for nearby physical infrastructure (use get_infrastructure) or a combined multi-factor site verdict (use analyze_site)'). It also gives a concrete example ('Is this Phoenix parcel water-constrained for a 100MW build?'), making usage clear.

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

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

Annotations already declare readOnlyHint=true, and the description adds behavioral context: returns US markets + ISOs, an ISO rollup, a grid-headroom leaderboard, and with a paid key, the transition thesis. 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?

Description is front-loaded with the core purpose and well-structured, though slightly verbose. Every sentence adds value, but could be trimmed slightly for efficiency.

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 no output schema, the description thoroughly explains the return shape: US markets + ISOs, ISO rollup, grid-headroom leaderboard, and paid key content. It covers the tool's predictive nature and prerequisites.

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

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

Schema description coverage is 100%, with both parameters clearly described in the schema. The description adds the example 'max_months=24' but does not add new meaning beyond the schema.

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

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

Description clearly states the tool is a forward-looking radar for emerging hyperscale-friendly grids, specifies verb 'returns', and distinguishes from retrospective reports and sibling tools like get_interconnection_queue and rank_markets.

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

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

Explicitly states when to use (forward-looking emergence) and when not to, with clear alternatives: 'Do NOT use for the current ISO queue snapshot (use get_interconnection_queue) or a present-day market ranking (use rank_markets).' Also provides a usage example: 'Try: grid_transition_radar max_months=24.'

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

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

Beyond the readOnlyHint annotation, the description adds behavioral details: 10-min refresh, pulls from dchub news pipeline, uses regex for extraction, classifies by actor. 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?

Four sentences, each adding value: purpose, data source, refresh, usage guidance. Front-loaded with main function. No fluff, but could be slightly more concise. Overall well-structured.

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

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

Given the tool has one parameter, no output schema, and readOnlyHint annotation, the description provides complete context: data source, refresh rate, what it extracts, and usage boundaries. No gaps for a live feed 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?

Only one parameter 'limit' with full schema coverage (100%). The description does not add extra meaning beyond the schema's own description of the parameter. Baseline 3 is appropriate as the schema already covers the semantics.

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

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

The description clearly states it's a live feed of specific AI-capex deals (Stargate, OpenAI, etc.), extracts dollar figures and MW, and classifies by actor. It distinguishes itself from siblings like list_transactions and deal_autopsy, making the purpose unambiguous.

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

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

Explicitly tells when to use (tracking AI capex events, capacity announcements, competitive intel) and when not to use (use list_transactions for historical M&A comp set, use deal_autopsy for single-deal teardown). Provides clear alternatives.

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

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

Annotations already declare readOnlyHint=true, and the description adds context about the return structure (array with fields) and persistence. No contradictions, but no extra behavioral details beyond 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 informative but slightly wordy; however, it includes necessary examples and caveats without being excessive. Good front-loading of key 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 zero parameters, no output schema, and annotations providing readOnlyHint, the description covers purpose, usage, return structure, and sibling differentiation completely.

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?

No parameters; baseline 4 applies. The description explicitly states 'Params: none', which is clear.

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

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

The description clearly states the verb 'list' and the resource 'saved sites', and differentiates from siblings like save_site and export_dataset. Example queries reinforce the purpose.

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

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

The description explicitly says when to use (when user asks to see shortlist) and what not to use (add site or download as file), with named alternatives. Also mentions it's free with a key.

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. The description adds context beyond annotations: data coverage (2019-present, 2,000+ deals), disclosure limitation (many private deals undisclosed), and the returned fields. No contradictions. Could mention pagination behavior but not required.

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 brief (4 sentences) and front-loaded: first sentence states purpose, second lists outputs, third lists filters, fourth gives example and exclusion guidance. No filler 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 10 parameters and no output schema, the description covers the return format (list of fields), scope (sector, time range), and alternative tools. Does not mention default sort order or pagination behavior (limit/offset), but these are covered in the schema. Adequate for the 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?

Schema coverage is 100%, so baseline is 3. Description adds value by highlighting key filters (year, min_value_usd, region, buyer, target) and providing an example that demonstrates using year and min_value_usd together. This clarifies which parameters are most impactful.

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 lists M&A and capital transactions in the data center sector, specifies the return fields, and distinguishes from sibling tools (hyperscaler_deals, deal_autopsy) by name. The verb 'list' is implied and the resource is well-defined.

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 (broad M&A and capital-deal flow) and when not to use (hyperscaler-specific lease/PPA/JV activity → use hyperscaler_deals; single-deal post-mortem → use deal_autopsy). Provides an example call with reasoning.

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 indicate readOnlyHint: true, and the description explains the output is indicative auto-routed corridors not engineered, subject to survey. This adds relevant behavioral context beyond annotations, though more detail on data sources would improve clarity.

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 (a few sentences) and well-structured: purpose, example, parameters, output summary, and exclusions. Every sentence adds value, and the most 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?

Despite no output schema, the description clearly describes the output fields (length, GeoJSON, diversity, cost) and their indicative nature. Parameters are fully covered. The tool's complexity is moderate, and the description provides sufficient context for an AI agent to use it effectively.

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

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

All parameters have schema descriptions (100% coverage), and the description adds additional context: defaults, examples, optionality, and allowed values for fibre and bore_m. This enriches understanding of how to use each parameter.

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

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

The description clearly states the tool's purpose: planning N diverse, road-following fibre lead-in routes. It includes a concrete example and distinguishes itself from sibling tools like analyze_site and get_fiber_intel.

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 (planning fibre routes) and when not to use (site-suitability or fibre-provider footprints), naming alternative tools. This provides clear guidance for selecting the correct tool.

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

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

Discloses that it uses linear trend extrapolation, is not a guarantee, bands widen with horizon and short history, and declines with insufficient data. This adds context beyond the readOnlyHint annotation, which is consistent.

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

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

Well-structured with purpose, params, return, honesty note, and exclusions. Slightly verbose but all sentences add value. Front-loaded with main purpose.

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

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

Given no output schema, the description fully explains the return structure and covers edge cases (needs >=3 snapshots). It's complete for the tool's 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?

Schema covers both parameters fully, but the description adds extra context: e.g., market_slug required and valid slugs from specific tools, horizon_quarters default 4 with example '2 = ~6 months ahead'. This improves usability.

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 forecasts a DCPI market's near-term trajectory (next 1-8 quarters) and provides specific use cases like 'is this market trending toward BUILD or AVOID?'. It distinguishes from siblings such as get_market_dcpi_rank and rank_markets.

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

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

Explicitly tells when to use (trend questions) and when not to use ('Do NOT use for a single point-in-time verdict' or to rank many markets). Also notes requirement of at least 3 daily snapshots, providing clear usage boundaries.

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

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

Annotations already declare readOnlyHint, and the description adds detailed behavioral context: it returns a structured object with specific fields, explains parameters and defaults, and provides example inputs.

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

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

Well-structured and front-loaded with use case and example, but slightly long. Every sentence is informative, so no waste, but could be trimmed 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 (4 params, no output schema), the description is complete: explains input semantics, return format, example use, and exclusions, enabling correct 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?

While schema coverage is 100%, the description adds significant value by explaining each parameter with examples, defaults, and constraints beyond the schema's brief 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 provides a ranked list across 300+ markets, with a specific verb 'rank markets'. It distinguishes from siblings like get_market_intel and analyze_site by stating what it is not for.

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 (for top N markets) and when not to use (deep read on one market or scoring lat/lon), providing a clear example and alternatives.

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

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

The description adds extensive behavioral details beyond the readOnlyHint annotation: deterministic, normalization contract, signed weights, hard constraints fail-closed, percentile vs absolute normalization, cross-run stability. 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 provides essential detail for correct usage, given tool complexity. It is front-loaded with the main purpose and well-structured. Minor reduction possible but justified.

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

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

Given the tool's complexity (7 params, no output schema), the description fully covers inputs, behavioral edge cases (missing field fail-closed, percentile baseline), and integration with other tools. Complete guidance for accurate invocation.

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

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

Schema coverage is 100%, and the description adds significant meaning: explains signed weight convention ('+weight maximizes, -weight minimizes'), fail-closed behavior for constraints, options for absolute vs percentile, and shortlist_name mechanics. Adds value beyond 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: deterministic multi-site ranking under constraints, with a specific verb (rank) and resource (sites). It distinguishes from siblings like analyze_site (one site) and get_refined_queue (candidate set).

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 ('pick the best N sites under constraints') and when-not-to-use ('for one site use analyze_site; to get the candidate set first use get_refined_queue'). Also explains how to pass data from other tools, giving clear 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 goes beyond annotations by detailing that the key is never returned over the wire, the confirmation is identical regardless of existence (enumeration-safe), and the key is emailed to the bound address. This provides rich behavioral insight.

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 with two main sentences plus usage guidance. It is well-structured, front-loading purpose and mechanism, then adding security and usage notes without redundancy.

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

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

The tool is simple with one parameter and no output schema; the description covers what it does, how it works, the return value (neutral confirmation), and security aspects. It is fully complete for an agent to invoke correctly.

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

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

Schema coverage is 100% and the description adds meaning by explaining the required email parameter, its role in re-sending the key, and that it is never returned over the wire.

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 'recover', the resource 'lost DC Hub key', and the mechanism of re-sending to email. It uniquely identifies the tool's purpose among siblings like 'claim_free_key' and 'bind_email'.

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: when the human lost a key and knows the email. It provides clear context but does not explicitly mention when not to use or list alternatives.

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

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

Annotations (readOnlyHint=false, destructiveHint=false) are consistent with description labeling it a WRITE operation. Description adds useful context: it's FREE, builds persistent shortlist, returns site id, and suggests monitoring via alerts. 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?

Front-loaded with purpose in first sentence. Includes usage, example, and exclusions. Slightly verbose but efficient. Every sentence contributes meaning.

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

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

For a write tool with 7 optional parameters, no output schema, and annotations, the description fully covers purpose, prerequisites, expected output, follow-up actions, and exclusions. No 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 coverage is 100%, so baseline is 3. Description adds value by naming key parameters (lat, lon, name, state, market, target_mw, notes) and providing an example call. This reinforces semantics beyond the schema's individual 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 verb+resource: 'Save a candidate data-center site to your DC Hub account to track it across sessions.' It also differentiates from sibling tools by explicitly listing what not to use it for (e.g., list_saved_sites, export_dataset, score_facility).

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 (saving a site), prerequisites (need a key, claim_free_key if not), and follow-up action (pass id to set_site_alert). Excludes alternatives with 'Do NOT use to read back...'.

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 annotation 'readOnlyHint: true' indicates no mutation, but the description describes saving/persisting data, which is a write operation. This is a direct contradiction, undermining trust. Even ignoring the annotation, the description doesn't fully disclose side effects (e.g., overwriting behavior).

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

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

The description is a single, well-structured paragraph with key information front-loaded. It is concise but includes essential details; every sentence adds value. Slightly verbose for the behavioral contradiction, but otherwise efficient.

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

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

The description covers persistence, scoping to API key, and pairing with retrieval. However, it lacks details on error handling (e.g., duplicate shortlist name), capacity limits, or performance considerations. With no output schema, the description should slightly expand on these aspects.

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 coverage is 100%, but the description adds significant value beyond the schema by explaining the expected structure of 'site' (lat/lng/capacity_mw + metric fields), the semantics of 'objectives' (signed weights), and examples for 'shortlist_name'. This helps the agent understand parameter interdependencies.

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 ('save a site'), the target resource ('PERSISTENT, named shortlist'), and distinguishes from siblings like 'save_site' and 'get_shortlist' by emphasizing persistence across conversations and pairing with re-scoring.

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 use case ('build a durable siting shortlist across days/weeks') and suggests pairing with 'get_shortlist' for re-scoring. It lacks explicit when-not-to-use or direct alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint=true. Description adds detail on return structure (composite score, tier, peer comparison, per-dimension detail) and weighting options, providing valuable 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?

Packed single paragraph with purpose, usage, parameters, return, exclusions, and example. Efficient, though slightly dense; could benefit from minor structuring.

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?

No output schema exists, yet description adequately explains return fields (composite, tier, peer comparison, per-dimension detail). Covers inputs, outputs, and exclusions, making it complete for this tool's 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?

Schema coverage is 100%, but description explains weighting enum values (balanced default, power_priority, etc.) and clarifies that facility_id comes from a prior search. Adds meaning beyond schema.

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

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

Description clearly states it grades an existing facility across 7 dimensions with a 0-100 score. Contrasts with siblings like analyze_site, compare_sites, find_alternatives, making its unique purpose evident.

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

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

Explicitly says when to use (independent grade for one facility) and when not (raw lat/lon, compare, find alternatives). Includes a concrete example with example query and parameter 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 declare readOnlyHint=true, and description confirms read-only. Adds context on return format and linking to fetch tool. 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?

Concise three-sentence description with no wasted words, front-loading purpose and immediately stating format and usage. Efficient use of space.

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 simple single-parameter tool with no output schema, the description covers purpose, return format, and follow-up actions. Minor omission: no mention of error cases or pagination, but appropriate for the tool's simplicity.

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 a clear description of the query parameter. Description does not add new meaning beyond the parameter's schema description, so 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?

Clear verb 'Search' and specific resource 'DC Hub' with return format {id, title, url}. Distinguishes from sibling search_facilities by noting free-text vs structured queries.

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: free-text queries. Provides alternative: 'use search_facilities directly' for structured queries. Also guides how to use results: pass id to fetch tool or open url to cite.

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, so description does not need to reiterate safety. Description adds context about scope and returns, which is sufficient.

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?

Single, well-structured paragraph: purpose, return fields, example, usage guidelines. Every sentence adds value.

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

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

Given 10 params, no output schema, and presence of sibling tools, the description is complete: it defines scope, return fields, provides an example, and gives usage guidance. Agent can select and invoke correctly.

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

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

Schema coverage is 100%, so description adds marginal value beyond parameter descriptions. The usage example demonstrates parameter combination, but no extra semantic detail for individual params.

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 searches 21,000+ data center facilities with multiple filters, specifies return fields, and explicitly distinguishes from sibling tools like get_pipeline and get_facility.

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 (find EXISTING facilities) and when-not-to-use with named alternatives (use get_pipeline for pipeline, get_facility for full profile).

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

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

Annotations already provide readOnlyHint=true. Description adds that it returns 'most relevant cited records', which is consistent but adds minimal behavioral context. No mention of rate limits, authentication, or potential side effects. 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?

Two sentences, directly stating purpose and return type. No redundancy or fluff. Could be slightly more structured but remains efficient.

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

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

No output schema; description only mentions 'most relevant cited records' without detailing output format, pagination, or error handling. For a search tool with readOnlyHint, it covers basic intent but lacks depth expected for a semantic search.

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 4 parameters. Description adds context about corpus types (news, M&A, etc.) and natural-language query, slightly reinforcing schema but not adding significant new meaning beyond 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?

Description clearly states semantic search over DC Hub intelligence corpus listing specific content types (news, M&A, facilities, market analysis). However, it doesn't explicitly distinguish from the sibling tool 'semantic_search', which may have overlapping functionality.

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?

No guidance on when to use this tool versus alternatives. Does not mention exclusions or prerequisites. The description only states what it does, not when to prefer it over similar sibling tools like 'search' or 'semantic_search'.

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

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

Annotations declare readOnlyHint=true, consistent with a read-only search. The description adds transparency about the return structure (ranked results with citable source fields) and the scoring mechanism (relevance ranking). 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 a single well-organized paragraph that front-loads the purpose, then provides examples, parameter details, and return format. It is efficient but could benefit from slight structuring with bullet points or clearer separation of sections.

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 no output schema, the description explains the return format (fields like source_table, kind, text, score, cite). It covers all necessary aspects: purpose, usage, parameters, return, and alternatives. The tool is complex with multiple corpora and the description fully addresses the context.

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

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

The input schema already describes all 4 parameters with 100% coverage. The description adds value by providing default values (k=8, corpus=all), clarifying the required nature of q (though schema says 0 required), and giving usage examples. This is above the baseline of 3.

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