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

With no annotations, the description carries the full burden. It discloses valuable behavioral context such as returning two separate lists, lease-level vs well-level granularity, and the measurement basis. However, it does not disclose return ordering, response format, or how the optional category parameter alters behavior. It is more transparent than the tool name alone but incomplete.

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 sentence that packs in all essential details: the resource, limits, geography, granularity, and time basis. There is no filler, and the most important scope details are 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 tool with only two enum parameters and no output schema, the description provides enough context to correctly call it: it says the state selection, the output scale, the level per state, and the metric. The main gaps are response shape and category-specific behavior, but they are minor given the tool's 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?

Schema description coverage is 0%, so the description must compensate. It partially does by tying state to lease-level (TX) vs well-level (OK) and implying both oil and gas outputs, but it does not explicitly explain the behavior of the category parameter or the fact that default is 'both'. The meaning is mostly inferable from the description but not fully documented.

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 a verb ('Get top 500 oil-producing wells AND top 500 gas-producing wells'), defines the geographic scope (Texas lease-level vs Oklahoma well-level), and specifies the sorting criterion (latest reported monthly production volume). This distinguishes it clearly from siblings like get_top_operators and get_new_producing_wells.

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 a clear use case for retrieving top-producing wells but provides no explicit guidance on when to choose this tool versus alternatives. It does not mention exclusions or contrast with sibling tools like get_top_operators or get_new_producing_wells.

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