nasa-power-mcp-server

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

Annotations only cover read-only and open-world status, and the description adds substantial behavior beyond that: per-site failures preserve successes, duplicate labels keep separate input-position identities, sort uses nulls-last with stable ties and rejects mismatched/unknown units, and oversized payloads stage completely with summaryDatasets/summaryIndex preserving ordered arrays. These are non-obvious traits an agent could not infer from any structured field.

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?

Purpose and scope are front-loaded in the first clause, followed by sorted behavioral detail with no filler sentences. The final sentence ('Oversized observations and summaries stage completely; summaryDatasets handles and summaryIndex preserve complete ordered summary arrays') is compressed to the point of being hard to parse on first read, which costs a point.

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

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

For a complex multi-branch schema (four temporalResolution variants, nested selection oneOf) with an output schema present, the description covers the compatibility rules, partial-failure semantics, sorting behavior, and staging outputs. Nothing an agent needs before calling is missing, and return values are correctly left to the output schema.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above baseline by explaining what the sort parameter actually does (which means it uses, tie-breaking, unit-compatibility rule) and by explaining staging/canvas_id reuse. It does not re-explain the scalar fields already documented in the schema, which 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?

States a specific verb and resource — comparing 2–10 labeled coordinates with a shared parameter selection and window — plus the default resolution (climatology). The multi-site framing implicitly separates it from single-site siblings like nasa_power_get_timeseries and nasa_power_get_climatology, but no sibling is named explicitly.

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 2–10 location constraint and climatology default imply the intended usage, but the description never states when to pick this over nasa_power_get_timeseries, nasa_power_get_region, or nasa_power_dataframe_query, nor any exclusion conditions. Guidance is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context beyond the annotations: canvas tokens are process-local capabilities and inspection is confined to the supplied canvas, which tells the agent about scoping and side-effect boundaries it could not infer from 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?

Two sentences, front-loaded with what is inspected, followed by the scoping constraint. No filler, though the phrase "original scientific provenance" is slightly abstract and 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?

With an output schema present, return values need not be explained, and the description covers scope, content (schemas, units, provenance), and token semantics. It is complete enough to call correctly, with only the sibling-routing guidance left unstated.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the table parameter's "omit to inspect this canvas" behavior. The description adds no syntax, token lifecycle, or multi-table semantics beyond what the schema states, 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 uses a specific verb ("Inspect") against specific resources ("table schemas, physical units and original scientific provenance") within a named scope ("canvas_id"). It is clearly distinguishable from data-fetching siblings like nasa_power_dataframe_query, but it never names or contrasts them explicitly.

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

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

Usage is implied through the prerequisite "a canvas_id returned by a producing POWER tool," which tells the agent this is a follow-up step to another call. However, there is no explicit guidance on when to choose this over nasa_power_dataframe_query or when inspection is unnecessary.

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?

Goes well beyond the readOnly/idempotent/closed annotations: discloses the refusal list, the 1,000-row and 40,000-character caps, and the subtle truncation semantic that rowCount counts only materialized rows. This is exactly the behavioral context annotations cannot carry.

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 dense sentences, each carrying distinct information: scope, alternative tool, refusals, and limits. The core 'what it does' is front-loaded with zero 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?

With an output schema present, return values need no explanation; the description still covers safety profile, restrictions, and result-size limits, which is everything an agent needs to invoke it correctly. The truncation caveat closes the one subtle 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?

Schema coverage is 100% (baseline 3), and the description adds value by explaining the effective row cap and the 40,000-character truncation behavior tied to rowLimit, plus the read-only constraint on sql. It doesn't spell out the canvas_id token format, but the schema already does.

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 ('Run one read-only SELECT over tables') scoped to an explicit canvas_id, and routes to the describe sibling for name/unit inspection. An agent can distinguish this from the fetching siblings (get_timeseries, get_climatology) without opening a schema.

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

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

Explicitly says to use nasa_power_dataframe_describe to inspect names and units before querying, giving a clear alternative for that subtask, and enumerates what is refused (external files, imports, writes, system catalogs). It does not contrast against the data-fetching siblings, so it falls short of a full when/when-not map.

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

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

Annotations already cover safety (readOnlyHint) and open-world scope, yet the description still adds real behavior: omitted years fall back to the source product range, small profiles return inline while large ones return a table handle plus bounded preview preserving orientation text, and canvas_id reuses a prior workspace. No auth, quota, or error behavior is disclosed, but the response-shape behavior is a genuine value add.

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 short sentences, front-loaded with what the tool retrieves before falling into operational detail. Dense but every sentence carries a distinct fact; the only slightly opaque phrase is 'preserving orientation text'.

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 12 parameters, an output schema, and full schema descriptions, the definition covers the non-obvious parts: year pairing, preset vs explicit parameter selection delegation, and the inline-versus-canvas return split. The remaining gap is the lack of contrast with the timeseries sibling, which matters given seven 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%, so the baseline would be 3; the description exceeds it by stating the startYear/endYear must be supplied together and letting omitted years default to the product range, a coupling the schema does not express. It also explains the canvas_id reuse flow, though it says nothing extra about units, community, or windSurface/windElevation pairing.

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 (retrieve climatology) with the temporal scope (monthly and annual) and spatial granularity (latitude/longitude). This inherently separates it from nasa_power_get_timeseries, though the contrast is never made explicit.

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 routes the agent to nasa_power_list_reference for presets and to nasa_power_search_parameters indirectly via the selection schema, which is useful usage context. However, it never says when to choose climatology over the sibling timeseries or region tools, so the main selection decision is left to inference.

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

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

Annotations already state readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context — equal-weight per-period cell statistics rather than area-weighted, and that oversized results are staged with previews, counts, and SQL handles queried via summaryDataset in summaryIndex order. That is useful but stops short of stating limits, quotas, or how large a request must be before staging kicks in.

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

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

Every sentence carries a constraint or routing rule, and the core purpose is front-loaded. It is dense to the point of being a single block, and phrases such as 'summaryDataset in summaryIndex order' assume reference knowledge rather than being self-contained.

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 three oneOf variants, an output schema, and 100% schema coverage, the description supplies exactly what structured fields cannot: region-size limits, antimeridian handling, staged-result workflow, and the statistical semantics of the returned cells. An agent can call this correctly without further 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 description coverage is 100%, so the baseline is 3, but the description adds constraints the schema does not encode: the 2–10 degree span per axis, single-parameter restriction, and the prohibition on year fields for climatology. It leaves canvas_id, units, timeStandard, and community entirely to the schema, which is acceptable given their documentation.

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

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

The first sentence gives a specific verb (retrieve), resource (one parameter over latitude/longitude bounds), and hard scope limits (2–10 degrees per axis, single parameter, three temporal resolutions). It immediately separates the tool from point-based siblings by describing region bounds and by naming nasa_power_get_climatology as the point alternative.

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 routing rules are present: use nasa_power_get_climatology for custom years at a point, split antimeridian regions into separate calls, and note that regional climatology takes no year fields. These are concrete when/when-not conditions an agent can act on without opening another schema.

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

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

The annotations already declare this as a read-only, open-world operation. The description adds useful behavioral context by noting that large results return a full-table canvas handle and preview, and it clarifies resolution-specific date requirements. It does not mention authentication or rate limits, but the added return-handling behavior is meaningful.

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

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

The description is front-loaded with the core purpose, then gives the key resolution-specific requirement, then names helper tools and oversized-result behavior. Every sentence contributes useful information with no apparent waste.

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 complex oneOf-based schema, 100% parameter description coverage, and an output schema, the description covers the essential calling context: resolution-dependent date fields, parameter-code lookup, preset lookup, and large-result handling. It is nearly complete, though it could do more to distinguish this tool from related climatology and comparison siblings.

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

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

Schema description coverage is 100%, so the schema already carries most parameter meaning. The description reinforces the date parameter differences between hourly/daily and monthly modes and points to helper tools for parameter codes and presets, but it adds limited semantic detail 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 uses a specific verb and resource: retrieve hourly, daily, or monthly observations at latitude/longitude. It clearly distinguishes ancillary helper tools for parameter codes and presets, but does not explicitly distinguish this tool from siblings such as nasa_power_get_climatology or nasa_power_compare_locations.

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

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

It states the key date requirements for each temporal resolution and directs the agent to nasa_power_search_parameters for codes and nasa_power_list_reference for presets. It does not explain when to choose this tool instead of related siblings like climatology or location comparison, so it stops short of full when-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by stating that reference entries include public documentation and verification dates, which tells the agent what kind of authoritative content to expect.

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

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

Three sentences, each with a distinct job: state what the reference covers, give usage guidance, and describe entry contents. It is front-loaded and has 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?

An output schema exists, and annotations cover safety and idempotency, so the description does not need to explain return values. It is nearly complete for a one-parameter reference tool, though it could say a bit more about the remaining topic values.

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

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

Schema description coverage is 100%, so the enum and default are already documented. The description still adds value by mapping the enum topics to human-readable concepts and by explaining when to choose 'presets' versus 'coverage', going beyond the bare schema description 'Reference topic'.

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

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

The description clearly identifies a reference-lookup tool and enumerates the domains it covers: presets, communities, units, source coverage, missing values, wind corrections, and dataframe availability. It does not explicitly name sibling tools, but the phrase 'before a producing call' distinguishes it from the data-producing calls in the sibling list.

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

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

It gives concrete usage guidance for two key topics: use 'presets' before a producing call, and use 'coverage' when revising a date window. It does not explain when to choose the remaining topics, but the guidance is clear enough to route the main workflows.

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, the description explains that whitespace-separated filter tokens must match code, name, or definition case-insensitively. It also states that filtering covers the complete dictionary before sorted pagination, which clarifies matching and pagination 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 front-loaded and compact, moving from core purpose to filter semantics to pagination behavior to next-step usage. Each sentence contributes useful information without repetition.

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

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

The tool has annotations, full schema descriptions, and an output schema, so return-value details are not needed. The description sufficiently covers purpose, filtering behavior, pagination scope, and how to use the returned codes.

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 documents parameters well. The description adds meaningful semantics for the filter parameter, including whitespace-token matching against code, name, and definition, plus the blank-filter browse behavior and pagination scope.

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

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

The description uses a specific verb and resource: it finds parameter codes supported by a community and temporal resolution. It also distinguishes the tool as a discovery step by saying returned codes should be passed to a producing 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?

It gives clear usage guidance for the filter: blank filter browses all codes, and returned codes should be passed to a producing tool. It does not explicitly name sibling alternatives such as list_reference, but the context is otherwise clear.

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