Get well by API number

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 behavior of handling different API formats (dashes, state prefixes) and the fallback matching strategy. It also reveals that if state is omitted, it iterates over all states, which implies potential performance implications. This is good coverage beyond what the schema provides.

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, which is concise and front-loaded with the main purpose. The first sentence defines the function and output. The second sentence adds important behavioral details about formatting tolerance and multi-state search. Some redundancy with the schema examples is present, but the description as a whole is tightly written without 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 the tool's moderate complexity (two parameters, one optional enum), the description covers everything an agent needs: the output format (raw + summary), the handling of input variations, the matching algorithm, and the behavior when state is omitted. No additional context is necessary 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?

The schema already provides a clear description of the api parameter (with examples) and the state parameter (with enum). The description adds nuance that the api parameter tolerates formatting differences and that state is optional but speeds up the lookup. This meaningfully enhances what the schema states, so a 4 is warranted.

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?

States the specific verb ('Look up') and resource ('a specific well by API number'), and clearly defines the output as the full raw record plus the normalized summary. It distinguishes itself from siblings like search_wells and wells_near by focusing on exact API lookup rather than broad search or proximity.

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 explains when to use this tool: to retrieve a specific well by API number, and even notes that omitting the state will try every state (slower, but still functional). While it doesn't name alternatives, it implies that for broader search one would use search_wells or wells_near, and for raw queries raw_query. The description of the matching fallbacks (exact, bare digits, contains-match) also guides usage in edge cases.

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