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

With no annotations, the description carries the behavioral disclosure burden, and it does so well: it reveals that detection is peer-relative, that bad weather never raises an event, and that each fault is returned as a dated event with duration and energy cost. It does not cover pagination, limits, or permission requirements, but the core behavioral model is clearly disclosed.

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

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

The description is dense but efficient: it front-loads the core behavior, then gives use cases, then the competing-tool routing, then a key detection caveat. Every sentence earns its place and none are redundant.

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-style tool with no output schema and no annotations, the description explains the return value sufficiently by listing what each fault event contains. It also handles the main ambiguity around long windows and weather-related false positives. Minor gaps remain around output format details and explicit read-only labeling, but the description is largely complete for correct invocation.

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

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

Schema description coverage is 100% for all three parameters, and the schema already explains nodeId, startDate, and endDate semantics. The description adds context about the 'day-by-day record' and the window-length preference, but does not add substantial parameter-level meaning beyond the schema, so a 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?

The description states a specific action and output: 'Walk a site's day-by-day record and return every fault as a dated event' with clear event fields. It also explicitly distinguishes itself from diagnose_site by explaining what diagnose_site cannot see, so an agent can tell them apart.

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 use cases: 'what is wrong with this site', 'when did it start', 'how much has this cost us', and work-order feeds. It also gives a direct routing rule: 'Prefer this over diagnose_site for any window longer than a few days' with a concrete reason.

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 supplied, the description carries the full behavioral burden. It does disclose that the tool ranks nodes by output, but it doesn't explicitly state the operation is read-only or describe any side effects, rate limits, or edge-case behaviors (e.g., what happens when nodes have missing data). The core ranking behavior is clear, but additional transparency would be valuable.

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 two sentences, front-loaded with the primary action and scope, followed by concrete use cases. Every sentence contributes purpose and context without redundancy. It is appropriately concise.

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 should explain what the tool returns. It mentions 'rank them by output' but doesn't specify the format (e.g., a table, list, metric) or how the aggregation parameter affects the ranking. It also doesn't mention limits on the number of nodes or date-range constraints beyond the schema. For a comparison tool, more detail on the output shape is needed.

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 all parameters have description in the schema. The tool description adds the context of a shared date range and ranking by output, but it doesn't add syntax, format, or interaction details beyond the schema. This matches the baseline for full schema coverage.

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 ('Compare', 'rank') and resource ('several nodes'), with a clear scope (same date range, single query). It distinguishes itself from likely siblings like query_datum or get_energy by emphasizing cross-node comparison and ranking, so an agent can immediately tell what this tool does.

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 offers concrete use cases ('which sites are underperforming, how does this site compare to the rest, which node should I look at first') that clarify when to use it. However, it doesn't explicitly state when NOT to use it or name alternative tools for single-node queries, so it's clear on the 'when' but not on the 'when-not'.

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 that the tool runs asset_review internally and that a reference is auto-generated if omitted, which are valuable behaviors. However, it does not clarify whether the tool is a pure read/compute or writes persistent data, despite an outputPath parameter that implies file writing. It also omits any error or side-effect details. This partial transparency earns a 3.

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 three-sentence description is compact and front-loaded. The first sentence states the core purpose and output content; the second covers the internal-call routing; the third explains format semantics. Every sentence earns its place with no fluff or 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?

With no annotations and no output schema, the description must be self-sufficient. It covers the report’s structure, the internal call, and format interpretations. It does not describe error scenarios or return values, but given the tool is a generator that writes files, the basics are covered. The presence of an outputPath parameter and its schema description already conveys the write behavior, so the description is adequately 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the meaning of each format beyond the enum: 'pdf' for a printable field pack, 'markdown' to paste into a ticket, and 'json' to post-process. This directly helps the agent pick the right format. No other parameters are elaborated in the description, but their schema descriptions are sufficient.

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 clear, specific purpose: 'Turn a site's faults into a service request that a person can act on' and enumerates the report's constituents (prioritised jobs, plain-language account, evidence, steps, tools, sign-off criteria). It also names a sibling (asset_review) and explicitly tells the agent to call this tool instead, making the differentiation 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 direct usage guidance: 'Runs asset_review internally, so call this directly rather than reviewing first' tells the agent when to prefer this over the sibling. It also explains the three format options with their intended use cases (pdf for printable pack, markdown for ticketing, json for post-processing). It does not spell out exclusions for other siblings, but the context is clear 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?

With no annotations, the description fully carries the behavioral burden. It reveals the comparison logic, the weather-control mechanism (irradiance), and the three mutually exclusive diagnoses (dead inverter, reporting gap, bad weather). This is rich, actionable context far beyond a typical one-liner.

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 with zero fluff. The methodology is front-loaded, followed by the fault distinctions, then the practical usage examples. Every sentence contributes to the agent's understanding.

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

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

The description covers the core algorithm and use cases, which is the essential knowledge for calling this diagnostic tool. However, with no output schema present, it does not explicitly state what the tool returns or mention any prerequisites beyond the parameters. The missing return format is a minor 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% with clear parameter descriptions (nodeId, inclusive/exclusive dates, aggregation enum). The description only references 'a date range' and does not add semantic meaning beyond the schema, 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?

The description uses a specific verb ('Diagnose') with a precise resource ('solar site') and method ('comparing each inverter against its own siblings, with irradiance as the weather control'). It further enumerates three distinct fault outcomes, clearly differentiating it from generic tools like get_anomalies or compare_fleet.

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

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

The description provides explicit when-to-use scenarios: 'is anything wrong at this site', 'which inverter is broken', or 'why did output drop'. It does not, however, name alternatives or state when not to use the tool, so it stops short of a full 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly indicates this is a read operation, scoped to nodes where an anomaly output is published, and enumerates the contents of each reading (predicted value, actual value, error, irradiance, ANOMALY/NOMINAL status). It does not state what happens when no output is published or whether results are ordered, which are minor gaps for a read-only 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 sentences, each adding value: the first defines the operation and scope, the second specifies the returned fields, and the third gives usage context plus a concrete example. There is no padding, and the essential information is front-loaded.

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 three-parameter read tool with no output schema, the description adequately covers the return contents and gives a sibling reference for cross-checking. It could additionally state the behavior when no anomaly output is published, but overall the description is sufficient for an agent to call the tool correctly with the schema's help.

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 descriptions for nodeId, startDate, and endDate already present. The tool description adds context about the readings but does not enhance parameter-level meaning beyond the schema, such as date range interpretation or the effect of omitting startDate. Baseline 3 is appropriate because the schema already documents the parameters.

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

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

The description opens with a specific verb and resource: "Read the output of the platform's own ML anomaly detector for a node." It clearly distinguishes this from siblings by emphasizing the platform's own ML verdict, and later contrasts it with computing one's own verdict and with diagnose_site. An agent can tell exactly what this tool does and what it does not do.

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 states when to use the tool: "Use this when you want the platform's own verdict rather than computing one yourself, and to cross-check what diagnose_site concluded." It names the alternative (diagnose_site) and provides a decision rule, plus a concrete public example node for testing. This is strong 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?

No annotations are provided, so the description carries the full burden. It discloses that this tool computes from meter readings rather than averaging instantaneous power, which is a key behavioral trait. However, it does not describe the response shape, how missing readings are handled, or whether results are summed across multiple node IDs. For a no-annotation tool, this is adequate but with room to add more behavioral context.

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, no wasted words. The core purpose and key differentiator are front-loaded, and the usage guidance follows naturally. Every sentence earns its place.

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 5 parameters, no output schema, and no annotations, the description gives purpose, usage context, and a critical behavioral distinction. It does not explain the return value, but for a reporting-oriented tool, this is a notable gap. Still, the description is strong enough that an agent can decide when to use it and what to expect conceptually.

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 covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds a little semantic value by explaining why 'Difference' is the usual reading type, which helps an agent understand the default parameter. However, it does not go into detail about the date format or node-local time, which is already in the schema.

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

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

The description states a specific action ('Get true accumulated energy') with a precise resource ('meter readings') and unit ('watt-hours'). It explicitly contrasts with averaging instantaneous power, distinguishing it from siblings like get_latest and query_datum without needing to open their 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?

The description explicitly says when to use it: for 'how much did this site generate' questions and reporting/billing-shaped needs. It also gives a reason (averaging loses accuracy). It does not explicitly name alternative tools to use instead, but the context signals and sibling list imply there are other query tools, so the guidance is clear but not fully exclusionary.

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 behavioral disclosure burden. It adds useful interpretation beyond the schema by noting that generation is legitimately zero at night and that weather/irradiance are included where available. This helps the agent avoid misreading valid nighttime data as a failure.

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 short sentences, each earning its place: the first states the core behavior, the second gives the primary use case, and the third provides a critical interpretation caveat. It is front-loaded and free of 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 read-style tool with two well-documented parameters and no output schema, the description is largely complete. It explains purpose, when to use it, and a key data-interpretation nuance. A small gap is that it does not describe what happens when no recent reading exists or how to interpret missing sources, but this is minor.

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 documents nodeId and sourceIds. The description reinforces the per-source aggregation concept and the optional restriction to specific source IDs, but does not need to add substantial parameter-level detail.

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 retrieves the most recent reading per source on a node, including weather and irradiance when available. This distinguishes it from siblings like query_datum or get_energy by focusing on latest status rather than history or aggregates.

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 the agent when to use it: for 'what is happening right now' and for checking if a stream is still live. It does not explicitly name alternatives or exclusion criteria, but the context is clear enough for correct selection.

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. It discloses that nodes are readable without credentials, that the catalogue comes from scanning IDs 1-5000, and that dead nodes should be filtered to avoid stale data. It does not mention output format or rate limits, but these are less critical for a simple list operation.

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: purpose, usage guidance, and filtering tip. Every sentence earns its place, with the core behavior front-loaded and no wasted words.

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 two optional parameters and no output schema, the description adequately covers purpose, scope, and usage. It could mention what fields are returned or how results are ordered, but an agent can invoke the tool correctly with the information provided.

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. The description adds a rationale for the liveOnly parameter ('avoid ones that stopped reporting years ago') but does not add new meaning for either parameter beyond what the schema already 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 states the tool lists SolarNetwork nodes that are publicly readable, sourced from a catalogue built by scanning node IDs 1-5000. This is a specific verb+resource and differentiates it from sibling tools that operate on known nodes or sources.

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 instructs to use this tool first when no node ID is available, and explains why (no public endpoint that enumerates nodes). It also advises filtering to live nodes to avoid stale entries, but it does not name alternative tools for when a node ID is already known.

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 of behavioral disclosure. It clearly indicates a read-only listing operation ('List'), explains the classification logic, and additionally discloses that it returns the node's data window and timezone, which is beyond a simple listing. It does not mention error conditions or rate limits, but for a simple retrieval tool this is acceptable.

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 two sentences, both of which are purposeful. The first sentence front-loads the core function and classification details, the second provides a usage directive. There is no fluff or redundancy, and each sentence earns its place.

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 a single parameter, no output schema, and no annotations, the description covers all necessary aspects: what it does, what it returns (streams classification, data window, timezone), and when to use it. Nothing essential is missing for an agent to correctly invoke this 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?

The schema description coverage is 100% (nodeId is fully described as 'SolarNetwork node ID'). The tool description does not add any additional meaning to the parameter beyond what the schema already provides. Per the baseline rule, when schema coverage is high, a score of 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?

The description states a specific verb ('List') and resource ('streams reporting on a SolarNetwork node') and details the classification categories (GEN, INV, PYR, WEA). This clearly distinguishes it from sibling tools like get_latest or query_datum, which focus on data retrieval rather than listing structural information about a node.

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

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

The description provides explicit usage guidance: 'Always start here when you do not already know what a node measures.' This tells the agent the exact trigger condition for using this tool and implies that if the node's measurements are already known, other tools may be more suitable. While it doesn't name specific alternatives, the contextual cue is strong and actionable.

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?

Since no annotations are provided, the description carries the burden of behavioral disclosure. It discloses that 'watts' is averaged power (not total) and points to get_energy for true totals, which is a meaningful behavioral nuance. However, it doesn't mention whether the tool is read-only or any potential side effects, though as a query that is implied. It could also disclose behavior around multiple sources or response size, but the key nuance is covered.

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, front-loaded with the core purpose, and every sentence adds value. It packs essential information into three sentences with no fluff, and the alternative tool reference is clearly positioned at the end. Structure is effective for quick agent parsing.

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 query tool with 5 parameters all documented, no output schema (so the description's summary of returned metrics is essential), and guidance on parameter selection, the description is complete. It covers what the tool does, how to use it, and where to go for alternative functionality. There are no missing pieces an agent would need 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?

The schema covers all parameters with descriptions (100% coverage), so baseline is 3. The description adds value by providing aggregation selection guidance (Day, Hour, Month) that goes beyond the enum values, effectively helping the agent choose the right parameter value. It also clarifies the semantics of the 'watts' output, which is related to the data returned. This elevates it above the 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?

The description clearly states the tool queries time-series data over a date range with aggregation, accepts multiple nodes, and returns specific metrics (mean power, total energy, mean irradiance). It uses specific verbs and resources, and distinguishes itself from get_energy by clarifying the difference between averaged power and true energy totals.

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 provides explicit guidance on when to use different aggregation periods (Day for week-to-month, Hour/FifteenMinute for single-day shape, Month for year trends) and explicitly names an alternative tool (get_energy) for energy totals, telling the agent when NOT to use this tool.

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