nempulse

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

No annotations are provided, so the description must carry the full transparency burden. It does communicate the type of data returned (revenue, dispatch, SOC, FCAS) and an example DUID, but it does not disclose return format, pagination, rate limits, or behavior for invalid DUIDs. For a read-only tool this is acceptable but not rich.

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 that front-loads the core purpose ('Deep-dive metrics') and immediately provides the parameter scope and examples. Every word earns its place, with no filler or 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?

For a tool with one parameter and no output schema, the description adequately conveys what data will be returned by listing the metric categories. It does not specify units, time range, or structure of the response, but these are acceptable gaps for a simple lookup tool. The example DUID mapping adds helpful context.

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

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

Schema description coverage is 100% for the single 'duid' parameter, providing the attribute name and example. The description adds the specific example mapping 'HPR1 = Hornsdale', giving useful real-world context beyond the schema. This enriches the parameter meaning without being redundant.

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 provides deep-dive metrics for a single battery, listing specific metrics (revenue, dispatch, SOC, FCAS) and the DUID parameter. It distinguishes itself from sibling tools like get_battery_revenue (which likely focuses only on revenue) and get_fleet_summary (fleet-level). However, it lacks a strong action verb like 'retrieve' or 'get', making it slightly less 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?

The description gives clear context: use this tool when you need detailed metrics for one battery identified by DUID. It does not explicitly mention alternatives or when not to use, but the specific scope and metric list imply when it's appropriate. An explicit reference to sibling tools would raise it to 5.

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 transparency. It discloses that the tool returns all DUIDs (requiring client-side filtering) and clarifies the benchmark nature (energy-only, perfect-foresight). However, it does not explicitly state side-effect-free read behavior, output formatting, or any rate limits, which are relevant given the complete absence of annotations.

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

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

The description is very concise: two short sentences with the key information front-loaded. Every phrase ('actual vs LP-optimal', 'per-DUID summary', 'energy-only') adds meaningful detail without waste. There is 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?

For a simple two-parameter read-only tool with no output schema, this description provides the essential information: what it computes, the unit of analysis (per-DUID), the time range, and a key behavioral note (returns all DUIDs). It is sufficiently complete for an agent to invoke the tool correctly without further clarification.

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%: both parameters (date_from, date_to) are already described with their format (YYYY-MM-DD) and semantics. The description only adds 'over a date range,' which is consistent but adds no new meaning. Following the baseline rule for high schema coverage, this merits a 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 what the tool does: calculates 'Actual vs LP-optimal dispatch revenue, per-DUID summary' and returns all DUIDs. It uses specific domain terminology (LP-optimal, DUID) and distinguishes itself from sibling battery tools like get_battery_detail and get_battery_revenue by focusing on the LP-optimal benchmark comparison.

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 comparing actual dispatch revenue against a perfect-foresight benchmark, but does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or conditions. The context 'energy-only, perfect-foresight benchmark' gives some situational guidance, but no explicit directives.

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 must carry the burden. It adds useful behavioral constraints such as 'Daily grain only' and specifies revenue components (energy + FCAS). However, it does not disclose output format, date range limits, error behavior, or auth/permission requirements, leaving some gaps for a no-annotation 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 extremely concise: two short sentences, front-loaded with the essential purpose and key constraints. No redundant or filler words, and every phrase adds value.

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 low-complexity tool with 3 well-documented parameters and no output schema, the description covers the core aspects: what revenue (daily, gross-spot, energy+FCAS), for which entity (one battery DUID), and over what period. It lacks explicit response structure, but this is a minor omission for such a simple query tool.

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%, with each parameter already documented (e.g., DUID example, date format). The description adds no extra parameter semantics beyond what's in the schema, so the baseline score of 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 precisely states what the tool returns: daily gross-spot revenue by market, including energy and FCAS, for a single battery identified by DUID, over a date range. This clearly differentiates it from sibling tools like get_battery_detail or get_fleet_summary.

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 conveys clear usage context: use for daily revenue data for one battery. It does not explicitly mention alternatives or when not to use, but the sibling tool names imply complementary functions, making the intended scope evident.

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?

No annotations are provided, so the description carries the full burden. It discloses the output scope and fields, but does not mention any limits (e.g., data size, ordering), inclusion/exclusion of retired units, or whether it's a snapshot. As a read-only list, it's reasonably transparent but not exhaustive.

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?

A single, front-loaded sentence with an efficient parenthetical list of output attributes. Every word earns its place; no redundancy or fluff.

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

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

Given zero parameters and no output schema, the description adequately defines the returned data (fields) and the universe (NEM-registered grid-scale). It could mention whether any optional filtering exists, but with no parameters, it's nearly complete. A minor gap is the absence of any note about response format or scale.

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 has zero parameters, so the baseline is 4. The description adds value by specifying the output fields, which is helpful since there is no output schema. No parameter descriptions are needed.

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 ('List') and resource ('every NEM-registered grid-scale battery'), and enumerates the returned fields (DUID, station, region, MW/MWh, MLF, coordinates). This clearly distinguishes it from sibling detail tools like get_battery_detail.

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 usage context is implied: it's for listing all batteries. However, it does not explicitly state when to prefer this over siblings or mention any exclusions/alternatives. There is no guidance on when not to use 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?

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 burden and compensates well by disclosing the operational behavior: it generates SQL, returns result rows, and provides an explanation. It does not mention read-only status or error behavior, but for a simple query tool the disclosure is solid.

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 that front-loads the action ('Ask a natural-language question') and resource ('NEM BESS data'), followed immediately by return types. Every word earns its place with zero 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 one-parameter tool with no output schema, the description adequately covers what the caller can expect regarding return values. It could add guidance on question phrasing or limitations, but the core usage context is complete enough given the low complexity.

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 only parameter 'question' is already fully described in the schema (100% coverage), including its type and max length. The tool description adds no additional parameter-level meaning, so the schema does the heavy lifting, which aligns with 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 clearly states the tool accepts a natural-language question about NEM BESS data and returns generated SQL, result rows, and a plain-English explanation. This separates it from the sibling getters/listers, which are specific data fetch tools, 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 implies that this tool is for natural-language queries rather than specific parameterized calls, but it does not explicitly state when to use it over the sibling tools, nor does it name alternatives or exclusions. Usage context is only implicit.

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