eia-energy-mcp-server

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

Annotations already declare readOnlyHint=true, and the description adds valuable context: the isLeaf flag, that leaf routes are queryable endpoints, and the normalization of slashes (in the parameter description). It does not mention error handling or empty results, but the core behavior is well disclosed.

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

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

Three sentences that are tightly packed with meaning: purpose, usage guidance, behavior, and routing to a sibling. No fluff, and the key information is front-loaded. This is exemplary conciseness.

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

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

With a present output schema and readOnly annotation, the description covers the essential browse flow, initial steps, and the switch to eia_describe_route. Minor gaps like invalid paths or empty results are not addressed, but they are not critical for a browse tool given the existing structured fields.

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

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

Schema description coverage is 100% for the 'path' parameter, including examples and slash normalization. The main description adds 'Start with no path' which slightly reinforces the omit-root behavior, but this is largely redundant. The schema already does the heavy lifting, so baseline 3 applies.

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

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

The description clearly states the tool's function: 'Lists child routes under a given path in the EIA dataset taxonomy.' It names the 14 top-level categories and explicitly contrasts with eia_describe_route, making the tool's unique role unambiguous even among siblings.

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

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

Provides explicit instructions: 'Start with no path to get the 14 top-level categories... then drill into subcategories.' It also gives a concrete conditional: 'When isLeaf is true on the browsed path itself, switch to eia_describe_route.' This tells the agent exactly when to use this tool and when to hand off.

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

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

Beyond the readOnly and idempotent annotations, the description discloses that entries for dataframes no longer held by the canvas are dropped before responding, non-staged names return found=false rather than an empty list, and that polling does not extend expiry. These are critical stateful behaviors an agent must know.

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 densely packed with zero verbosity: each sentence carries new information—purpose, staging prerequisite, parameter usage, error case, and expiry distinction. It is front-loaded with the core function and then layers essential nuances.

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 (listing/inspecting dataframes with provenance, expiry, schema) and its interaction with sibling tools, the description covers all operational aspects: staging prerequisite, staleness handling, error return semantics, and the expiry distinction from eia_dataframe_query. The presence of an output schema further reduces the need to explain return values, leaving no gap.

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

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

The schema already documents the name parameter at 100% coverage, and the description repeats the omit-to-list-all behavior. However, it adds meaningful semantics by explaining that a non-staged name returns found=false and that listing does not affect expiry, which goes beyond the schema definition.

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

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

The description states a specific verb (list/inspect) and resource (canvas dataframes), and clearly scopes the tool to dataframes materialized by eia_query_route with stage:true. It explicitly contrasts with eia_dataframe_query on the expiry behavior, distinguishing its role without ambiguity.

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

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

The description gives explicit usage guidance: omit the name to list all, provide a name to inspect one, and explicitly states that listing does not extend expiry—only eia_dataframe_query does. It also clarifies that an empty list means no staging has occurred, not failure, which is essential context.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description reinforces these by explicitly listing rejected operations. It adds behavior not in annotations: VARCHAR casting requirements, expiry extension for referenced dataframes, and the semantics of register_as (fresh expiry, name uniqueness). This goes beyond the annotation baseline, though it does not cover every edge case (e.g., performance or transaction 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 dense but efficient. It leads with the core purpose, then covers constraints, data type caveats, and optional chaining in a logical order. Every sentence conveys essential information without filler. It is longer than average, but the complexity of the tool justifies it — no word is wasted.

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 of this complexity, the description covers all critical aspects: prerequisites, supported and rejected operations, data type handling, output truncation behavior, expiry semantics, and register_as usage. The output schema likely captures return format, so nothing critical is missing. This is a model of a complete tool description.

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

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

The schema already provides detailed descriptions for all four parameters (100% coverage), so the baseline is 3. The description adds value by explaining how the sql parameter must reference df_<id> handles, giving an example, and clarifying the interplay between preview and register_as (lower preview when chaining). It also deepens register_as's meaning with reuse rules. This is more than the schema alone offers.

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

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

The description opens with a specific verb and resource: 'Run a single-statement SELECT against canvas dataframes'. It clearly distinguishes this from sibling tools by referencing dataframes registered by eia_query_route and listing them via eia_dataframe_describe, and implies it is the querying counterpart to those route-management tools.

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

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

Explicitly states the prerequisite: dataframes must have been staged (stage: true) or there is nothing to select. It enumerates supported SQL features and lists rejected operations (writes, DDL, DROP, etc.), provides a concrete example, and explains when register_as should be used for chaining. This leaves an agent with no ambiguity about when and how to use the tool.

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

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

With readOnlyHint=true, the bar is lower, but the description still adds valuable behavioral context: it discloses that facet values are fetched from separate EIA endpoints and merged, that results are cached per-route for the process lifetime, and it explains the capped window with value_count and values_truncated plus the empty-window notice. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: purpose, usage ordering, pagination mechanics, and caching. It is front-loaded with the core purpose and avoids redundancy. Despite being longer than average, it is tightly written with no filler.

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

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

Given the tool's complexity (multiple parameters, pagination, merging behavior) and the existence of an output schema that defines return values, the description covers all aspects an agent needs: what the tool does, when to call it, how to paginate, and caching implications. Nothing essential is missing.

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

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

Schema coverage is 100% and each parameter already has a meaningful description. The tool description adds extra guidance beyond the schema, such as how to use facet and values_offset together to page through truncated results and what happens with offset past the end. This exceeds the baseline of 3 for full coverage.

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

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

The description clearly states the tool returns metadata for a leaf route and enumerates exactly what that metadata includes (facets, columns, units, frequency, date range). It distinguishes itself from siblings by explicitly naming eia_query_route as its predecessor and implying that route discovery is done via eia_browse_routes/eia_search_routes.

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

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

The description gives explicit when-to-use guidance: 'Call this before eia_query_route to discover valid facet IDs...' It also explains pagination usage (pass facet and values_offset) and the behavior when paging past the last value. This effectively tells the agent how to sequence operations relative to siblings.

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

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

The description discloses that data values are strings and need casting in SQL, that one upstream request is made by default, and that stage:true pages past the preview and incurs extra latency. It explains the staging side effect and requirement of a canvas. This goes well beyond the readOnlyHint annotation, providing complete transparency about side effects and performance.

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

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

The description is compact yet information-dense. It front-loads the core purpose, then covers prerequisites, data type quirk, default vs. staging behavior, and integration with downstream tools. Every sentence earns its place with no redundancy or 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 tool with 10 parameters, nested objects, and an output schema, the description covers all necessary context: prerequisites, behavior for preview and staging, latency implications, data type handling, and routing to eia_dataframe_query. The output schema is present, so return-value explanation is not needed. Nothing an agent needs to invoke correctly is missing.

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

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

Schema coverage is 100% with detailed parameter descriptions (e.g., route slash stripping, stage behavior, filters keyed by facet ID). The description adds a useful note about data values being strings (relevant to numeric columns) and emphasizes the need to consult eia_describe_route for valid parameter values, but these are not parameter-specific over and above the schema. Since the schema already carries the heavy lifting, a 4 is appropriate for the marginal added 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 data from a leaf route with optional facet filters, date range, frequency, and column selection. It distinguishes itself from siblings by mentioning 'leaf route' and the preview/staging behavior, which is distinct from route discovery (browse/search) and route metadata (describe) tools.

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

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

It explicitly instructs to 'Use eia_describe_route first to discover valid facet IDs, facet values, column IDs, and frequency codes.' It also explains when to use stage:true ('turn it on when moving to analysis, not while exploring') and directs the user to pass the staged dataset name to eia_dataframe_query for SQL, providing clear routing among siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's job is to add context — and it adds a lot: first-call warm-up latency of 24-30s (up to 45s) vs. milliseconds on later calls, the indexComplete check, result semantics (isLeaf, filter_hint carrying filters), and the weak-match threshold. This is non-obvious behavioral disclosure that no annotation or schema could convey.

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

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

Dense but efficient — purpose is front-loaded and each subsequent clause adds value (matching behavior, facet handling, result fields, latency, indexComplete). The operational warm-up note is valuable rather than padding. It runs a bit long but no sentence is wasted.

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

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

With an output schema present, return values needn't be spelled out, and the description covers optimization/search-navigation guidance, result semantics (isLeaf, filter_hint, score threshold), and a critical operational quirk (warm-up latency, indexComplete). Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the schema documents both query and limit (default 10, max 30) — baseline 3. The description goes beyond this by clarifying query semantics: fuzzy matching, term-by-term multi-term matching, STEO series indexing, and facet-value resolution. It meaningfully enriches how the query parameter behaves in ways the schema cannot express.

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

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

States a specific verb and resource — 'Fuzzy text search across route names, descriptions, and category labels' — and explains the resolution goal (natural-language queries → matching route paths). This clearly differentiates it from siblings like eia_browse_routes (browse taxonomy) and eia_query_route (direct query), which the sibling list makes relevant.

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 routes the agent to eia_browse_routes when results are weak (score > 0.72), and distinguishes browsing further vs. querying directly via isLeaf. It doesn't enumerate every sibling differentiation (e.g., when to use eia_query_route vs. this for an exact known path), but the key exclusion condition and alternative are stated clearly.

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