nempulse

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

No annotations were provided, so the description bears full responsibility for disclosing behavior. It clearly states that certain metrics are month-to-date, that rte_pct is not window-scoped and null means 'not measured', and that commercial context affects revenue comparability. This is thorough and prevents misinference.

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 lengthy but each sentence carries essential information—warnings about units, date scoping, and commercial context are all critical. It is well-structured with distinct topics (date handling, rte_pct, commercial context) and avoids redundancy. No fluff present.

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, yet the description effectively communicates what metrics are returned and their semantic nuances (e.g., month-to-date vs daily, rte_pct null meaning, commercial_context implications). This gives the agent a complete picture of the tool's behavior and limitations, even without an explicit output contract.

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

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

The input schema already covers all parameters with 100% coverage, but the description adds meaningful context: duid uses 'HPR1' as an example, and date_from/date_to are explained as requiring both together and scoping the revenue/throughput stats. This enhances parameter understanding 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?

Clearly states the tool's purpose as providing deep-dive metrics for a single battery, listing specific metrics (revenue, dispatch, SOC, FCAS). It explicitly differentiates from sibling get_battery_revenue by pointing to that tool for true daily time series, making selection 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?

Provides explicit usage instructions: warns that 'rev_today' fields are month-to-date by default, explains how to get daily data via date_from/date_to (must be used together), and instructs users to always check commercial_context before comparing revenue across units. These directives are actionable and prevent misuse.

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 no annotations provided, the description must disclose behavior itself, and it does so richly. It reveals that both actual and optimal figures are MLF-adjusted, that the LP objective is solved on MLF-adjusted prices, that only solved LP days are included and failed days are dropped, that calls cannot match get_battery_revenue totals, that date_to may be silently truncated, and that timeouts are possible.

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

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

The description is long, but every sentence carries necessary operational or semantic information. It front-loads the core purpose and differentiates the tool from its sibling before covering MLF treatment, dropped days, truncation, and timeout guidance. Nothing in the paper 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?

This is a nontrivial tool with no output schema, yet the description anticipates potential misinterpretations and common pitfalls: revenue-total confusion, MLF adjustment, solver-failure days, silent date truncation, and timeout risk. For the complexity of the data returned and the absence of annotations, the description is remarkably complete.

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

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

The input schema already provides descriptions and 100% coverage for all three parameters, so a baseline of 3 is appropriate. The description adds meaningful operational semantics beyond the schema: duid restricts to one battery, omitting it scans all DUIDs and risks timeouts, and date ranges should be kept short. This goes beyond the schema's basic type descriptions.

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

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

The description opens with a precise statement of what the tool does: 'Actual vs LP-optimal dispatch revenue, per-DUID summary, over a date range'. It explicitly identifies the tool as a benchmark comparison and differentiates it from the sibling tool get_battery_revenue, including the key distinction that this is not a revenue-total source.

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 direct guidance on when to use this tool versus an alternative: 'NOT a revenue-total source — use get_battery_revenue for that.' It also provides operational guidance on parameters, explaining that omitting duid scans every DUID and can time out, and advises keeping date ranges short and retrying 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?

With no annotations provided, the description carries full burden for behavioral disclosure. It reveals that the tool returns daily grain only (no sub-daily), that energy_rev_mlf_adjusted can be null (not zero) when the LP backcast hasn't run, and explains why get_battery_optimal's 'actual' figure is not comparable. This provides solid behavioral context, though it omits details like authorization or rate limits, which are less critical for a read-only data 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?

The description is concise (3 sentences), front-loads the core purpose, then provides usage guidance and a specific note about the MLF-adjusted field. Every sentence adds value without redundancy.

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

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

Despite lacking an output schema, the description explains the key output fields (energy_rev, energy_rev_mlf_adjusted) and a critical behavior (null vs zero). It omits a full list of fields but covers the essential information for a revenue query tool. This is nearly complete for the use case.

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 each parameter described (e.g., duid example 'HPR1', date format 'YYYY-MM-DD'). The description adds that the date range is for daily grain only, but does not significantly extend parameter meaning beyond what the schema provides. With high schema coverage, baseline is 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 clearly states it returns daily gross-spot revenue by market (energy + FCAS) for one battery over a date range. It specifies the resource (battery), metric (revenue), and constraints (daily grain only). It distinguishes from the sibling get_battery_optimal, making the purpose unambiguous.

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

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

The description explicitly tells when to use this tool ('for total revenue questions') and warns against using get_battery_optimal as a revenue source, explaining why its figures differ. It also notes that MLF-adjusted figures are available here, eliminating the need to switch tools.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It adds one valuable limitation ('per-interval dispatch during the event is not exposed') which clarifies what data is unavailable. However, it does not mention what 'summary stats' includes or the nature of the return value, leaving moderate gaps.

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

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

The description is a single sentence, front-loaded with the core purpose, and includes a parenthetical caveat. Every word earns its place, 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 tool is simple (one parameter, no output schema), but the description does not fully explain what response to expect beyond 'summary stats'. The added caveat about per-interval dispatch is useful, but the lack of detail about the output format leaves the description somewhat incomplete for an agent expecting precise return 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 coverage is 100%, and the single parameter 'id' is already described as 'Event id'. The description adds no additional meaning about the parameter format or source, so it relies on the schema. This meets the baseline of 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 'Summary stats for one market price event by id' clearly identifies the specific verb (get), resource (market price event), and scope (summary stats, by id). It distinguishes itself from sibling tools like list_events (which lists events) and battery-related tools, 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 implies usage when you need summary stats for a single event and already have an id. It does not explicitly mention alternatives or when not to use it, but the 'by id' wording and sibling tool names (e.g., list_events) provide enough contextual 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?

No annotations are provided, so the description carries the full burden. The word 'snapshot' and the tool name's 'get' prefix imply a read-only, non-destructive operation, but the description does not explicitly state side-effect-free behavior, authentication needs, or data freshness. This is adequate for a simple getter but not richly transparent.

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

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

The description is a single, compact sentence with no filler. Every word earns its place by naming the resource and the four key data points.

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

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

For a zero-parameter read-only snapshot, the description covers the essential content. However, with no output schema present, it would benefit from clarifying units, data freshness, or return shape, making it slightly incomplete.

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 tool has zero parameters, so the baseline of 4 applies. The description adds useful semantic context by enumerating the specific metrics returned, which is more than the empty schema provides.

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

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

The description clearly identifies the resource as a fleet-wide snapshot and lists the exact metrics (unit count, total capacity, revenue month-to-date, average spot price). This distinguishes it from sibling tools like get_battery_detail, which focus on individual battery data.

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

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

The phrase 'Fleet-wide' implicitly signals this is the aggregate-summary alternative to battery-specific tools, giving the agent a clear context for when to use it. However, it does not explicitly name alternatives or state exclusions, so it falls short of full 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?

With no annotations present, the description carries the full behavioral burden and does an exceptional job. It discloses the annualisation formula, the fact that results are a rough simulator guide, the distortion factors for commissioning units, small FCAS-primary units, and longer-duration units, the meaning of null commercial_context, and the null-until-refresh 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 with the core purpose and every sentence carries substantive caveats or field definitions. However, it is quite long and weaves several related warnings ('do not compare', 'check labels', 'never pool') through one dense paragraph; a short structured 'when not to use' summary could make it easier to absorb.

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

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

Despite lacking an output schema, the description covers the output fields, the meaning of the derived metric, all major caveats, and the fallback behavior when data has not yet refreshed. Nothing essential for an agent to invoke this tool 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?

There are zero parameters and an empty input schema, so the parameter-semantics burden is essentially nonexistent. The description adds extensive meaning about returned fields and derived metrics, though those are output semantics rather than parameter semantics; baseline 4 is appropriate for a zero-parameter tool.

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 opening sentence is a specific, verb-led statement: 'List every NEM-registered grid-scale battery' followed by the exact fields returned. It also differentiates itself from ranking/comparison tools by explicitly saying it is 'NOT a performance ranking' and naming the sibling tools to use instead.

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

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

The description gives explicit when-not-to-use guidance: do not use it to compare units, rank performance, or answer 'which battery earns most', and names get_battery_revenue and get_battery_optimal as the correct alternatives. It also gives conditional checks like 'check BOTH labels' before comparing revenue and warns against pooling peer_comparable=false units.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the action and resource without mentioning side effects, pagination, return format, or read-only nature, leaving significant transparency gaps.

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

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

The description is a single, concise sentence that front-loads the action and resource. Every word contributes meaning, with no redundant or filler 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?

The tool is simple with only two optional parameters, but the description omits details about return format, ordering, or pagination. Since there is no output schema, the description should provide more context on what the response contains, making it adequate but incomplete.

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

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

The input schema includes full descriptions for both limit and region, covering 100% of parameters, so the description adds little beyond the schema. The phrase 'optionally filtered by region' merely repeats the schema's optional flag.

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

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

The description clearly states the action 'List' and the resource 'NEM spot-price events', including specific event types (negative, elevated, spike, extreme). This distinguishes it from the sibling get_event_detail, which focuses on individual event details.

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 implies usage for listing events, optionally filtered by region, which is clear from the context. However, it does not explicitly mention alternatives like get_event_detail for detailed views, though the purpose is distinct enough to infer.

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 no annotations provided, the description carries the full behavioral burden — and it excels. It discloses the 8-second execution cap that its own longer timeout does not extend, the silent all-null-rows failure mode from correlated subqueries, and the slower recomputation-from-dispatch_prices path for market_* questions. These are exactly the non-obvious failure modes an agent needs to 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 long (~150 words) but every sentence carries critical operational information: core function first, then timeout limits, then SQL-phrasing pitfalls, then reachable-table boundaries, then the recomputation caveat. It is front-loaded and dense rather than padded; the length is justified by the tool's complexity and footguns.

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 NL-to-SQL tool with no output schema and no annotations, the description covers the major landmines: timeout behavior, null-row failure mode, table reachability, and recomputation cost. Minor gaps remain — what happens on timeout (error vs empty result), and how to handle questions that can't be answered — but nothing an agent needs to invoke it successfully 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 effectively 100% (single 'question' param described as a plain-English question), so the baseline is 3. The description adds real value beyond the schema by explaining how to phrase the question: scope to one region-month, use window-function phrasing for top-N/bottom-N, and avoid questions that target unreachable cache tables. This is meaningful parameter-level guidance, not repetition.

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 ('Ask a natural-language question'), a clear resource (NEM BESS data), and the exact return shape (generated SQL, result rows, plain-English explanation). This clearly distinguishes it from the sibling structured-retrieval tools like list_bess_units and get_fleet_summary, which all appear to be direct data accessors.

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-not boundaries: market_* cache tables are NOT queryable, and questions should be scoped to roughly one region-month or less. It also warns against per-day correlated-subquery phrasing. However, it never names a sibling tool as the alternative for structured queries, so routing an agent to a fallback tool is left implicit.

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