nempulse

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

With readOnlyHint/idempotentHint already declaring the safety profile, the description still adds substantial non-obvious behavior: rev_today/energy_rev_today/fcas_rev_today/contingency_fcas_rev_today are month-to-date, rte_pct is not window-scoped and null means 'not measured', and the date_from/date_to pair scopes the window. These are exactly the traps an agent would otherwise fall into.

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?

Long but front-loaded and entirely load-bearing: purpose first, then the MTD warning, then window scoping, then the rte_pct caveat, then the commercial_context comparison rule. The all-caps emphasis is used sparingly on the two genuinely dangerous mistakes. No filler sentences.

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

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

No output schema exists, so the description carries the return-value burden, and it does: it names returned field groups, explains the MTD vs windowed semantics, defines null rte_pct, and describes commercial_context/commercial_note. Nothing an agent needs to call and interpret 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% (baseline 3), but the description goes well beyond it: it explains the coupling constraint that date_from and date_to are 'both required together', states what the window actually scopes (revenue/throughput stats) versus what it does not (rte_pct), and clarifies the month-to-date default when omitted.

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 (deep-dive metrics) and resource (one battery by DUID), enumerates the metric families returned (revenue, dispatch, SOC, FCAS), and explicitly distinguishes itself from the sibling get_battery_revenue for daily time series. An agent can tell it apart from the other 10 siblings 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?

Gives explicit when-to-use ('for a true daily time series use get_battery_revenue'), how to resolve input ('use list_bess_units to find it from a station name'), and a when-not-to-be-misled rule ('ALWAYS check commercial_context before comparing this unit's revenue against another'). Alternatives and exclusions are both 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?

Annotations cover the safety profile (readOnly, idempotent, non-destructive), but the description adds substantial behavior beyond them: MLF-adjusted vs gross figures, both totals restricted to solved LP days, the two tools' totals intentionally not matching, silent truncation of date_to, and observed timeout behavior even for single-DUID single-month scans.

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-loads the core purpose before the caveats, and nearly every clause carries non-obvious information. The heavy em-dash parentheticals make it dense and slightly harder to parse, but there is little 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?

For a read-only, 3-param tool with no output schema, the description covers purpose, exclusions, comparison caveats, and failure modes well. It is slightly thin on the actual return shape (per-DUID summary is named but not itemized), which is the only notable 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%, so baseline is 3, but the description adds real meaning: omitting duid scans every DUID and can time out, while passing it restricts to one battery. Date parameters are only constrained generically ('keep date ranges short'), and the date_to truncation caveat is a useful semantic addition.

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 resource and comparison (actual vs LP-optimal dispatch revenue) with a defined scope (per-DUID, date range, energy-only, perfect-foresight benchmark). It explicitly names the sibling it is NOT (get_battery_revenue) and why, so an agent can disambiguate without opening schemas.

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 not to use it ('NOT a revenue-total source — use get_battery_revenue') and when to pass duid (omit for fleet scan, but risks timeouts). It gives concrete operational guidance: keep date ranges short, retry narrower on timeout.

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 the read-only/idempotent safety profile, but the description adds genuinely useful behavior beyond them: daily-grain-only restriction, the fact that optimal's actual figure is MLF-adjusted and solved-days-only so totals won't match, and that energy_rev_mlf_adjusted is null (not zero) until the LP backcast runs. That null-vs-zero distinction is exactly the kind of trap an agent would otherwise misread.

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 the core purpose and grain, then routing guidance, then the MLF caveat. Dense but every sentence carries routing or semantics payload; the long parenthetical about get_battery_optimal is the only spot that 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?

With no output schema, the description carries the return-value burden and does so reasonably: names the revenue components (energy, FCAS), the daily grain, and the MLF-adjusted field with its null semantics. The full shape/naming of returned fields is not enumerated, but enough is given to call and interpret it 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 the baseline is 3; the description adds the daily-grain constraint that shapes how date_from/date_to can be used, plus returned-field nuance tied to the duid/lookup flow. It does not add syntax or format detail beyond the schema, so it sits just above baseline.

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

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

States a specific verb+resource+scope: daily gross-spot revenue by market (energy + FCAS) for one battery DUID over a date range, with daily grain. It explicitly distinguishes itself from sibling get_battery_optimal, so an agent can route without opening either 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 claims the revenue-question territory ('This is the tool for total revenue questions') and gives a when-not clause for get_battery_optimal, including why its 'actual' figure is not a valid revenue source. This is the when/when-not/alternatives pattern at full strength.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, yet the description adds substantial context: est_revenue is gross, energy-only, excludes FCAS, and is not MLF-adjusted, and per-interval dispatch is deliberately not exposed. That is real behavioral disclosure beyond the annotations, though it doesn't discuss auth or rate limits.

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 sentence, then the dense field glossary follows. It is long, but with no output schema each clause about return fields and their semantics earns its place; only the packed listing of unit_class/peer_comparable feels slightly dense.

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 must carry the return-value burden, and it does: it enumerates every battery row field, defines the response code meanings, sign conventions, and caveats on revenue and FCAS. An agent has everything needed to interpret the response 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 required id parameter, so the baseline is 3. The description goes further by telling the agent where the value comes from ('take the id from list_events'), adding sourcing semantics the schema alone does not convey.

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

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

States a specific verb+resource: 'One price event by event_id', immediately distinguishing it from the sibling list_events by being the single-event lookup. The scope (all online batteries, ranked by est_revenue) is also 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?

Gives clear sourcing guidance — 'take the id from list_events' — which directs the agent to the prerequisite tool, and warns to check the field labels before comparing units. It stops short of stating when NOT to use this tool versus e.g. get_battery_detail, so it lacks full exclusion 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful non-obvious behavior: fleet_rev_mtd is gross spot revenue over any window despite its name, avg_efficiency_pct is a capture rate and returns null when optimisation hasn't run, and commissioning units are excluded unless include_commissioning is true. It stops short of describing caching or volume but adds substantial context 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?

Front-loaded with the return payload, then caveats, then sibling routing in a single dense paragraph. Every clause carries information, though the field enumeration is long enough to be slightly heavy to scan.

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

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

There is no output schema, so the description must and does explain the return fields and their edge cases (null efficiency, gross-revenue naming caveat). Combined with the date-window defaults and sibling routing, an agent has everything needed to call it 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 the baseline is 3, but the description adds real meaning: it explains the month-to-date default, that fleet_rev_mtd spans whatever date_from/date_to window is set, and that include_commissioning toggles the efficiency figure specifically. This goes beyond the schema's terse field notes.

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 (fleet-wide snapshot for the NEM battery fleet) and enumerates the exact metrics returned, so the agent knows precisely what this tool yields. It also names the two sibling tools it is not, distinguishing it from get_battery_detail and get_rankings.

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: 'For one battery use get_battery_detail; for a ranking use get_rankings.' The default window behavior ('covers month-to-date unless date_from and date_to are given') further clarifies when the tool applies without arguments.

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 read-only, idempotent, non-open-world, but the description adds material behavior beyond them: a double fleet scan that is slow and can time out, exclusion of commissioning/CONTRACTED/TOLLED units from ranking (with the commercial-return rationale), movement against an equal-length prior period, and the caveat to check unit_class and peer_comparable before treating a gap as 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?

Front-loaded with the core purpose and metric definition, then layers caveats, exclusions and the sibling routing in a logical order. It is dense and sentence-heavy, but virtually every clause carries actionable information rather than 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 no output schema, the description carries the return contract itself, naming every row field and the movement column, and it covers exclusion semantics, performance caveats, and runtime limits. An agent has everything needed to call and interpret this tool correctly without opening anything else.

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, but the description goes further: it explains what capture_fc_pct vs capture_perfect_pct actually mean, and clarifies that include_arrangement changes whether CONTRACTED/TOLLED units are ranked at all. It does not restate enum/format details already in the schema, so the added meaning is real but not exhaustive.

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?

Opens with a specific verb+resource ('League table of merchant NEM batteries over a date range, ranked by capture rate by default') and defines the two headline metrics precisely (capture_fc_pct as revenue share of forecast-informed benchmark, capture_perfect_pct as share of the perfect-foresight ceiling). It also enumerates the row shape, so the agent knows exactly what it gets back and how it differs from the unit-level sibling get_battery_revenue.

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: 'For one unit's revenue use get_battery_revenue,' which disambiguates against the closest sibling. It also states the practical operating constraint (keep the range to a month or less; can time out on long ranges) and the exclusion condition plus its override (include_arrangement), covering when-not as well as when.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds meaningful behavioral context beyond them: it is a daily summary only and the raw 5-minute series is deliberately not exposed. This granularity limitation is not derivable from the annotations or schema and helps the agent avoid misusing the tool.

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 tight sentences, front-loaded with the core purpose before the granularity caveat and the sibling redirect. Every sentence earns its place with 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?

For a simple read-only, 3-param tool, the description covers what is returned (daily min/max/mean), the unit, the scoping constraint, and the data-granularity limit. With annotations covering the safety profile and no output schema needed, nothing critical 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 all three parameters described (region enum, inclusive date range), so the schema does the heavy lifting. The description adds the $/MWh unit and 'one region' scoping but no syntax details 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?

States a specific verb and resource (daily min/max/mean RRP for one NEM region over a date range), including units ($/MWh) and the exact metrics returned. An agent can distinguish this from sibling tools like get_battery_revenue or get_rankings without opening the 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 it 'for price context around revenue or events' and routes the spike-detection case to list_events, which is a clear alternative. It gives when-to-use context and one concrete exclusion, though it doesn't cover other possible siblings (e.g., query_nem_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?

Annotations already declare a safe read-only idempotent profile, and the description adds substantial context beyond them: the gross-revenue boundary (before costs, degradation, financing), the tier definitions and their reliability, the limitations of the FCAS cap and capture-ratio cohorts, and the screening (not forecasting) nature. This is exactly the extra behavioral disclosure an agent needs.

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 front-loaded: what it is, whose data, then the return shape, then caveats. Every sentence carries information, though the tier explanation is somewhat compressed and the block could be broken into shorter units for scanning.

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 carries the full burden of explaining returns, and it does: tiers, P10/P50/P90, energy_share/fcas_share, monthly series, and supporting cohort data. An agent know exactly what comes back and how much to trust it.

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

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

Schema coverage is 100% with enums on both parameters, so region codes and duration values are already fully documented in the schema. The description adds only a light restatement ('of a given duration in one region') without extra syntax or constraint detail, so the 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?

States a specific verb and resource (modelled revenue for a hypothetical 1 MW battery) and immediately scopes it as 'not a real unit', which distinguishes it from the sibling get_battery_revenue. The modelled/optimal-dispatch framing is 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?

Gives strong guidance on the returned tiers ('the only tier to use as a project case', 'an unreachable ceiling') and when not to rely on the result ('a screening estimate, not a forecast'). It stops short of explicitly naming the sibling to use for real units, but the 'not a real unit' framing routes the agent away from get_battery_revenue clearly enough.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it discloses that the whole fleet returns in one response with no filters, enumerates returned fields, and warns about distortion behavior (span-annualisation inflating commissioning units 1.5x-2.4x, FCAS-primary inflation, duration bias), null semantics for commercial_context, and peer_comparable pooling constraints. This is unusually rich behavioral disclosure.

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 front-loaded: purpose, then the DUID/usage directive, then the field list, then caveats. However it is very long and some caveat passages (the double-counting/anti-rescaling warning) are dense and repetitive; it could be tightened without losing 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?

There is no output schema, so the description must carry the return-value burden, and it does: it lists every returned field and explains the two most misusable ones (rev_per_mw_yr, commercial_context/peer_comparable) in depth. An agent has everything needed to call and correctly interpret the result.

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?

Zero parameters, so the baseline is 4. The description contributes field-level semantics (DUID, commercial_context, unit_class, rev_per_mw_yr), but those are return-value concerns rather than parameter meaning, so it does not push above the zero-parameter 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?

States a specific verb+resource and scope: 'Reference list of every NEM-registered grid-scale battery.' It also distinguishes itself from siblings by positioning itself as the resolution step ('turn a station name into the DUID the other tools need'), so an agent can tell clearly what this tool is for versus get_battery_detail or get_rankings.

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 it ('Call this first to turn a station name into the DUID') and when NOT to use it, naming alternatives: 'use get_battery_revenue over a matched window, or get_battery_optimal for capture' and 'Do not use it to compare units, rank performance.' This is textbook alternative-routing 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 cover the safety profile (readOnly, idempotent, non-destructive), so the description adds orthogonal value: default ordering (newest first), the ~100 KB truncation behavior when include_responses is true, and the meaning of is_open. That is exactly the payload-risk context an agent needs before choosing include_responses.

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-loads the definition, then filtering, then the include_responses caveat and the sibling hand-off in a logical order. It is dense and somewhat long due to the event-type taxonomy, but each clause carries information an agent would otherwise have to guess.

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 enumerates the returned fields (event_id, region, event_type, started_at, ended_at, duration_min, peak_rrp, avg_rrp, is_open) and warns about payload size, so nothing an agent needs to call and interpret this tool 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 baseline is 3. The description goes beyond it by defining the numeric price bands behind each event_type enum value and stating that filters combine (region, event_type, date range), which the schema alone does not convey.

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

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

States a specific verb+resource (list NEM spot-price events) and immediately defines what an 'event' is, including the threshold logic and the four type buckets. This distinguishes it from siblings like query_nem_data and get_regional_prices without requiring schema inspection.

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: set include_responses only when battery behavior is needed, keep limit small in that case, and use get_event_detail for a single event's responses. It names the alternative tool and the condition that selects 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 readOnly/idempotent safety, but the description adds the costly behavioral facts: slowest tool (~1 minute), AI-generated so the SQL should be verified, an 8-second SQL execution limit, and a known failure mode where per-day subqueries silently return all-null rows. That is well beyond what the annotations 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?

Front-loads the identity ('last resort'), then proceeds to cost, scope limits, a specific failure-mode warning, and finally the queryable data boundary. Every sentence carries operational information; nothing is redundant with the title.

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, and the description compensates by stating the return payload (SQL, result rows, short explanation). Combined with the data-scope list and the query-shaping warnings, an agent has everything needed to call this correctly and interpret the result.

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

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

Schema coverage is 100% and the schema already documents the single 'question' param with an example, so the baseline is 3. The description then adds a real constraint on the parameter's content — keep scope to roughly one region-month because wider aggregates blow the 8-second limit.

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+resource chain: takes a plain-English question, generates SQL over NEMPulse tables, and returns SQL, rows and an explanation. The opening clause 'Last resort for ad hoc questions the other tools cannot answer' explicitly differentiates it from all ten sibling getters.

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

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

Explicit when-to-use ('other tools cannot answer'), when-not (the market analysis tables are unreachable), and alternative-avoidance guidance ('For per-day top-N ... ask for a window function rather than a per-day subquery'). Performance and scope conditions are also given.

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