Behind the Watt

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

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states the data source and that the records are not BTW-verified, but provides no information about whether the operation is read-only, authentication requirements, rate limits, or any side effects. This is minimal transparency for a data retrieval 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 a single short sentence, which is concise but not structured. It lacks front-loading of key details like parameter usage or behavioral notes. It could benefit from additional sentences to improve clarity without being overly verbose.

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

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

Given the tool has two optional parameters and no output schema, the description is incomplete. It does not explain the response format, how parameters affect results, or any prerequisites. The agent lacks crucial information to use the tool correctly, despite the simplicity of the 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 0%, so the description must compensate for missing parameter explanations. However, the description does not mention the 'limit' or 'state' parameters at all. The agent must infer their purpose solely from the schema (e.g., integer with default, string with length constraints), which is insufficient.

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 a 'separately classified third-party reported project pipeline' and adds that these records are not BTW-verified. This gives a specific verb+resource and distinguishes it from sibling tools like get_dataset_summary or get_facility. However, the term 'announcements' is not directly explained, and the phrase 'separately classified' is somewhat vague.

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 this tool is for non-verified third-party data, suggesting it should be used when official verification is not needed. However, there is no explicit guidance on when to use this tool versus alternatives (e.g., get_dataset_summary for verified data) or 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 bears full responsibility. It discloses what the tool returns (date, totals, methodology, license, citation), implying it is a read-only operation. However, it does not explicitly state read-only, potential side effects, authorization requirements, or rate limits, leaving some behavioral aspects unclear.

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 of 14 words, listing the key attributes concisely. Every word contributes meaning, and there is no redundant or extraneous information.

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

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

Given the tool's simplicity (no parameters, no output schema), the description sufficiently lists the five main return fields. However, it omits details like data formats or example values, which could be helpful for an agent to interpret the output.

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 no parameters (0), and the schema coverage is 100%. The description does not need to add parameter information. It correctly provides no misleading or redundant parameter details, so the baseline score of 4 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 uses a specific verb 'Get' and clearly names the resource 'dataset summary'. It lists the specific components returned: canonical dataset date, verified fleet totals, methodology, license, citation. This clearly distinguishes it from sibling tools like get_announcements or get_facility, which serve different purposes.

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 no guidance on when to use this tool versus alternatives. There is no mention of use cases, prerequisites, or exclusions. While it is implicitly clear for a simple retrieval tool, explicit guidance is missing.

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 does not disclose authentication, rate limits, or error behavior (e.g., what happens if slug not found). Only mentions the data returned.

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 achieving purpose clarity, but could be slightly more structured (e.g., separate parameter explanation). 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?

Adequate for a simple retrieval tool, but missing description of slug parameter and error handling. Lists contents well.

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 0%, and the description fails to explain the 'slug' parameter, its format, or how to obtain it, despite it being the sole required parameter.

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 'Get' and identifies the resource as a 'verified facility dossier', listing its contents (units, permits, etc.), clearly distinguishing from sibling tools like search_facilities.

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?

Implies usage for retrieving a single facility by slug, but provides no explicit guidance on when to use this tool over siblings or 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 provided, so description carries full burden. It states returns published facts and capacity, but omits any disclosure of authentication needs, rate limits, result limits, pagination, or sorting behavior. Insufficient for a search 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?

Two sentences, front-loaded with purpose, no redundancy. Every sentence 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 search tool with 4 optional params and no output schema, the description covers basic purpose and output scope, but lacks behavioral details and parameter semantics. 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?

Schema coverage is 75% (min_mw lacks description). The description does not add any parameter-level guidance beyond what schema provides; min_mw remains undocumented. Baseline 3 reduced due to missing compensation.

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?

Specific verb 'Search', clear resource 'BTW-verified behind-the-meter power facilities', and scope 'published facts and capacity' with exclusion of announcements. Distinguishes from siblings (get_announcements, get_facility, get_dataset_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?

Explicitly excludes announcements, implying use of get_announcements for that purpose, but no explicit when/when-not guidance or mention of other siblings. Usage context is implied but not fully articulated.

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