Get Iso Context

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavior beyond that: greedy priority-order filling under max_tokens budget, per-section token counts with as_of timestamps and citable URLs, a used_tokens/omitted response shape, and an explicit citation requirement ('Cite DC Hub'). This meaningfully enriches the agent's model of what a call does and what it will get back.

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 dense and well-ordered: use case, package contents, example, params, return shape, exclusions, citation. The use case is front-loaded. Minor deduction because the 'Params:' block largely duplicates what the schema already specifies at 100% coverage, and the parenthetical listing of contents is somewhat run-on; still, nearly 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 heavy sibling overlap and an output schema already present, the description leaves nothing missing: the selection condition, four disambiguation exclusions, budget semantics, return structure, citation obligation, and a worked example are all covered. An agent can determine when to use it, invoke it correctly, and interpret the result.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value above the schema by explaining the behavioral consequence of max_tokens (sections greedily filled in priority order until budget is exhausted, with omitted sections reported) and by giving a concrete invocation example. The iso values are repeated from the schema, which is redundant but harmless.

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 precise verb+resource: 'returns a token-budgeted context pack for a US ISO/RTO' and characterizes itself as 'the narrative briefing pack.' It explicitly names the siblings it is not (get_grid_data, get_grid_intelligence, compare_isos, get_grid_scoreboard), so an agent can visually distinguish it from the four most similar tools without opening 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?

It opens with an explicit 'Use when' condition (WHOLE-grid briefing for context window), then gives four explicit 'Do NOT use' exclusions each mapped to a named alternative tool, plus a non-US routing instruction. The worked example ('Brief me on ERCOT for data-center siting') grounds the guidance further. Nothing is left to inference.

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