eia-energy-mcp-server

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

The description adds meaningful behavioral context beyond annotations: explains the isLeaf flag, leaf vs non-leaf semantics, that leaf routes are queryable endpoints, and that leading/trailing/doubled slashes are stripped. Even though readOnlyHint is already set, this extra information helps the agent understand the traversal behavior and expected outcomes.

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

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

The description is compact and well-structured: a clear first sentence, followed by usage flow and a conditional switch. No redundant text, every sentence serves a purpose.

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

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

The tool is a simple one-parameter browse operation, but the description covers the navigation pattern, the meaning of isLeaf, and the transition to another tool. With an output schema present, this is complete enough 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 already describes the path parameter, but the description adds extra meaning: 'Omit for root', examples like 'electricity' and 'petroleum/pri', and the slash-stripping behavior. 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 function: 'Lists child routes under a given path in the EIA dataset taxonomy.' It uses a specific verb ('Lists') and resource ('child routes'), and distinguishes it from siblings like eia_describe_route, eia_search_routes, and eia_query_route by focusing on browsing hierarchy rather than describing, searching, or querying.

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

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

Explicit usage guidance is provided: start with no path to get top-level categories, drill into subcategories, and switch to eia_describe_route when isLeaf is true. This clearly tells the agent when to use this tool vs 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?

Beyond the read-only and idempotent hints, the description discloses important behavioral edge cases: the meaning of an empty list on a fresh session, the automatic dropping of stale entries, the found=false response for un-staged names, and the lack of expiry extension. These details are not derivable from annotations and are crucial for correct agent expectations.

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

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

The description is front-loaded with the core purpose and then layers in essential edge-case behavior. Every sentence adds distinct value, and the length is appropriate for the complexity of the tool. It is well-organized with no filler or redundant repetition.

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

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

Given the tool's single optional parameter, a rich output schema (present, so return fields are covered), and thorough annotations, the description fully covers all behavioral nuances: empty list semantics, stale entry cleanup, specific-name lookup, unknown-name behavior, and the distinction between listing and querying for expiry. There are no obvious gaps in what an agent needs to know.

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

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

The schema already covers the single 'name' parameter at 100%, so the baseline is 3. The description adds meaningful semantics by explaining the optionality ('Pass a specific name... omit to list all') and the response shape for missing names ('found=false alongside the handles that are'). This goes beyond the schema's straightforward field description, justifying a 4.

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

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

The description opens with a specific verb ('List') and clearly identifies the resource ('canvas dataframes (df_<id>) materialized by eia_query_route calls that passed stage: true') and the scope ('with provenance, expiry, row count, and column schema'). It also distinguishes itself from siblings by explicitly contrasting with eia_dataframe_query, ensuring the agent understands this is a listing/inspecting tool, not a querying tool.

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

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

The description provides explicit when-to-use and when-not-to-use guidance. It says 'Pass a specific name to inspect one dataframe; omit to list all active dataframes' and cautions 'Listing is not use: only an eia_dataframe_query statement naming a dataframe extends its expiry,' naming the alternative tool and the consequence of misuse. This is a clear usage contract.

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 annotations (readOnlyHint, idempotentHint), the description discloses critical behaviors: rejection of DDL/DROP/COPY/PRAGMA/ATTACH and external-file functions, denial of system catalogs, VARCHAR data requiring CAST, register_as creating new dataframes with fresh expiries, and expiry extension for named dataframes. These operational details significantly exceed what annotations convey, fully informing the agent of restrictions and side effects.

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

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

The description is dense but well-organized, starting with the core action, then supported SQL features, data source references, restrictions, type caveat, and optional chaining. Every sentence conveys necessary operational information without redundancy. It is appropriately sized for a complex tool with multiple caveats.

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 (SQL engine, data type conversions, expiry management, chaining) and the presence of an output schema, the description comprehensively covers prerequisites, restrictions, data handling, and side effects. It explains return nuances like truncation and exact counts via register_as, making it self-sufficient 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?

Although schema already documents all 4 parameters (100% coverage), the description adds rich behavioral semantics: explains CAST for arithmetic, preview is for chaining via register_as, row_limit has a truncated:true side-effect with totalRows equal to cap, and register_as requires an unused name with a specific rejection/fix behavior. This goes well beyond baseline 3, providing edge-case and workflow guidance not in the schema.

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

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

The description clearly states the tool runs a single-statement SELECT against canvas dataframes registered by eia_query_route that passed stage:true. This specific verb+resource combination distinguishes it from siblings like eia_query_route (register queries) and eia_dataframe_describe (list dataframes), 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 provides clear context: you need staged dataframes, reference them by df_<id> handles, and standard DuckDB SQL is supported. It implicitly differentiates from eia_query_route by noting this is read-only and that un-staged queries leave no table. However, it doesn't explicitly name alternatives when this tool should not be used, only stating restrictions (no writes/DDL). Strong implied guidance but not fully explicit exclusions, so a 4 is appropriate.

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

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

Beyond the read-only and non-open-world annotations, the description reveals substantial behavioral details: capped facet value windows with value_count/values_truncated, pagination via facet and values_offset, behavior when paging past the end, and per-route caching for process lifetime. These are non-obvious and invaluable for the agent.

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

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

The description is efficiently structured: return value first, then usage, then pagination mechanics, then caching. Every sentence contributes unique information with no redundancy or filler.

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

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

The description covers the tool's purpose, workflow placement, pagination edge cases, caching, and data-merge behavior. Since an output schema exists, detailed return-value documentation is not required; the description is fully sufficient for safe and 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%, so the baseline is 3. The description adds meaning beyond the schema by explaining how facet and values_offset jointly control pagination, the truncation hint mechanism, and the empty-window notice, which enriches 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 metadata for a leaf route' and lists the specific metadata components (facets, values, column names, units, frequency, date range). It also distinguishes this metadata-discovery tool from the query tool by explicitly instructing to call it before eia_query_route.

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

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

The description explicitly says to 'Call this before eia_query_route' to discover valid IDs and codes, clearly placing it in a workflow. It does not explicitly state when not to use it or compare to siblings like eia_browse_routes, but the leaf-route scope and sequence make 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?

Adds critical behavior beyond the readOnlyHint annotation: all numeric values arrive as strings and must be cast to DOUBLE, the default call makes exactly one upstream request, and staging enables cross-join between tables from different routes. These are non-obvious and materially affect how an agent handles results, going well beyond what annotations state.

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

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

The description is compact yet information-dense, front-loading the core purpose and then layering workflow, data-type caveat, and staging behavior. A few phrases like 'whatever total says' are slightly opaque, but every sentence contributes distinct value. It could be tightened but is well-structured for a tool with this complexity.

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

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

Given the tool's complexity (10 parameters, nested objects, staging modes, and sibling integrations), the description covers the full execution model: discovery prerequisite, preview vs. staging behavior, string casting, and cross-join semantics. An output schema exists, so return values are documented elsewhere. The description leaves no major workflow gap for an agent invoking this correctly.

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

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

Schema coverage is 100% with detailed per-parameter descriptions, so the description need not repeat them. It does add context about the stage parameter's latency trade-off and the string-value gotcha, but that is more cross-cutting behavior than parameter meaning. The description adds minimal new parameter-specific semantics beyond the schema, earning the baseline 3.

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

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

The description opens with a specific verb+resource: 'Fetches data from a leaf route' with optional filters, date range, frequency, and column selection. It clearly distinguishes from sibling tools by naming eia_describe_route for discovery and eia_dataframe_query for SQL, establishing this as the data-fetching entry point.

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 workflow guidance: 'Use eia_describe_route first to discover valid facet IDs...' and 'then pass the returned dataset name to eia_dataframe_query for SQL.' It also clarifies when staging is worth enabling ('turn it on when moving to analysis, not while exploring'), giving concrete when-to-use and when-not-to-use context.

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

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

Beyond the readOnlyHint annotation, the description discloses significant behavioral traits: index warm-up time (24–30s first call, milliseconds later), the meaning of isLeaf in results, weak-match score threshold, and indexing of STEO/facet values. This enriches the agent's understanding of response timing and result interpretation.

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 function, followed by examples, then advanced matching behavior, result details, and performance caveats. Each sentence contributes unique information; there is no redundancy or irrelevant 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 the output schema exists, the description still covers crucial non-schema context: index warm-up latency, weak-match threshold, browsing alternative, and isLeaf/filter_hint semantics. This is enough for an agent to decide when to call and how to interpret results, with no major 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 the baseline is 3. The description adds meaningful semantics for the query parameter: multi-term matching strategy, term-by-term resolution, STEO index coverage, and facet value filtering via filter_hint. But it does not elaborate on the limit parameter, which remains sufficiently described in the schema.

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

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

The description clearly states a specific verb and resource: 'Fuzzy text search across route names, descriptions, and category labels' and explains it resolves natural-language queries to matching route paths. It distinguishes itself from sibling tools, notably by referencing eia_browse_routes for exploring the taxonomy when matches are weak.

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 this tool (natural-language queries, multi-term searches) and when to use an alternative: 'Results with score > 0.72 are weak matches — try a more specific query or use eia_browse_routes to explore the taxonomy.' It also provides operational guidance like checking indexComplete before interpreting empty results.

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