WellState Labs SB 1150 Screening (read-only)

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

Annotations already declare read-only, idempotent, closed-world, non-destructive behavior, so the safety bar is lower. The description adds genuinely useful context beyond that — the compliance-plan horizon date, the rate-label on plugging cost, and the explicit note that the Full Wellbore cross-check changes no outcome, count, or cost. It does not address cost/rate-limit or failure behavior for unknown operator numbers.

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 purpose is front-loaded, but the payload is one sprawling sentence with deeply nested parentheticals ('approaching by 2042-09-01 (compliance-plan horizon)', '(a cross-check only; ...)'), which is hard to parse. The information earns its place but the structure could be broken into a scope line plus a returned-fields list.

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?

An output schema exists, so return values need not be spelled out — yet the description's enumeration of claim counts, plugging cost, crossing schedule, and the cross-check caveat is accurate and helps the agent decide whether this tool answers the user's question. Only the absence of sibling routing keeps it from a 5.

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% and the single parameter already documents the six-digit format with leading zeros and an example. The description restates the same meaning without adding format, validation, or lookup semantics beyond 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?

States a specific verb and resource: returns one operator's SB 1150 screening exposure from the publication, keyed by RRC operator number. It's clear what the tool produces, though it never explicitly contrasts itself with siblings like screen_operators or list_operator_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?

Usage is only implied by the resource ('one operator's ... exposure'). There is no statement of when to prefer this over screen_operators or get_well, and no prerequisites or exclusions are given.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds meaningful behavioral context beyond that: every response carries labeled claims (DOCUMENTED_FACT, INFERENCE, UNKNOWN), two UNKNOWN claims travel with each count, the server computes and combines nothing, and plug_record is null on editions without a plug record.

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 key scoping sentence is front-loaded, but the body is a dense run of long sentences covering district modes, paging, claims labels, null behavior, and disclaimers. It is informative rather than padded, yet the volume and lack of structure make it harder to scan than it needs to be.

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 an output schema present, return values need not be spelled out, and the description still covers null-field behavior, claims labeling, and non-computation guarantees. The one gap is that it never contrasts itself with the screening tools, leaving the agent to infer when to reach for it.

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 a baseline of 3 applies. The description adds real semantics on top: district omission vs. supply changes the shape of the result, and rows_limit requires district plus first_year equal to last_year to page per-wellbore rows, which clarifies the constraint that the schema only implies.

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 a specific verb and resource ('Returns the publication's plug record') and immediately scopes what the record is: W-3 plug dates on the Railroad Commission Full Wellbore file, counted by reported year and district. It is clearly distinct from screening siblings, though it never names an alternative tool explicitly.

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 lays out three modes of use: no district → statewide year counts plus per-district counts; district → that district's years with state-funded plug numbers, well types and bases; rows_limit → per-wellbore rows for one district and one year. It does not name sibling tools or say when to prefer them, which keeps it below a 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuinely useful trust semantics — the definition of the verified field (bundled manifest recomputes to the pinned root hash, attestation matches the build-time digest) and version-dependent content (contract 1.4.0 adds plug record basis with DOCUMENTED_FACT/INFERENCE/UNKNOWN labels). That is real value beyond annotations, but the rest is a field inventory rather than behavior.

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 first sentence is a ~100-word run-on that enumerates nearly every field of the response, most of which the output schema already documents. The one genuinely non-obvious fact — the meaning of verified and the contract-1.4.0 conditional content — is buried at the end instead of being 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?

With an output schema present, return values need no explanation, yet the description spends most of its length on exactly that. What an agent actually lacks — when to call this versus verify_publication or get_plug_record — is never addressed, so the definition is complete on data shape but incomplete on routing.

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 takes zero parameters, so the baseline is 4. There is nothing to disambiguate, and the description correctly does not invent parameter guidance.

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 opening clause names a specific verb and resource: it describes the publication metadata served by this endpoint, and the enumerated fields (root hash, publication id, contract version, source file digest, rule parameters) make the resource concrete. It never distinguishes itself from the sibling verify_publication, whose subject matter it partly overlaps, so an agent must infer the boundary.

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?

There is no explicit when-to-use or when-not-to-use statement, and no named alternative among the eight siblings. The sentence about the verified field implies the tool also reports verification status, which makes the overlap with verify_publication more confusing rather than resolving 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?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered; the description adds genuinely new context about conditional field presence ('when the edition publishes it', 'when the edition carries it') and explicitly states the plug flag 'changes no outcome, count or cost', which prevents an agent from misreading it as an authoritative plug determination. It stops short of describing not-found or error behavior.

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 lead clause is well front-loaded, but the body is one sprawling sentence that enumerates roughly a dozen return fields. Since an output schema exists, that enumeration largely duplicates structured data and inflates the description at the cost of scannability.

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 an output schema present, the description need not document return values, yet it does so thoroughly and adds the conditional-presence and plug-flag caveats that matter for interpretation. The only real omission is behavior on an unknown or malformed API number.

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% and the api parameter's description already spells out the eight-digit, no-42-prefix, no-dashes format. The description restates the same constraint ('county code + unique number, no 42 state prefix') without adding new syntax or edge cases, so it neither compensates nor detracts — 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?

States a specific verb and resource — returns one wellbore's screening record keyed by API number — and anchors it to the Inactive Well Aging Report, which separates it from get_plug_record and get_operator_exposure without needing to open a schema. The record's domain (screening outcome, operator evaluations, plugging cost) is concrete enough to distinguish it from every sibling.

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?

Usage is implied rather than stated: the single-record, API-keyed lookup shape makes it obvious this is a point retrieval, and the note that the plug flag is only a cross-check hints at get_plug_record's role. But there is no explicit 'use this when…' or 'for plug details use X instead' routing, and nothing about what to do when the API is not found.

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?

Annotations already cover the read-only/idempotent safety profile, and the description layers on real behavioral detail: a 100-row page cap, totals that repeat on every page, next_cursor presence signalling more rows, and the constraint that a cursor is bound to the issuing publication root and refused otherwise. That is more than the structured fields convey.

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?

Ordering and paging facts are front-loaded and every sentence carries information, but the opening sentence bundles filter, sort, and tie-break rules into one long clause, and the cursor-binding sentence partly duplicates the cursor schema description.

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 an output schema present, return-shape explanation is optional, yet the description still tells the agent what comes back (rows, match count, cost total) and how to continue paging. Nothing needed to call this correctly is missing.

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 earns above that by explaining the outcome semantics (APPROACHING means affected by 2042-09-01) and the sorting consequences of the default limit. Cursor reuse rules are restated from the schema, so it does not reach 5.

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 names a specific verb and resource ('Lists one operator's wellbore claims from the publication') and pins down scope, filters, and sort order. An agent can distinguish it from siblings like get_well or get_operator_exposure without opening a schema.

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 gives clear operational guidance: default outcome AFFECTED, how to page (pass next_cursor back as cursor with the same operator_number and outcome), and that ALL means every claim. It stops short of stating when to prefer this over get_operator_exposure or screen_book, so it is clear context but not full alternative routing.

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?

The description goes well beyond the readOnly/idempotent/non-destructive annotations by disclosing row structure, P-5 letter handling, claims and cost semantics, NOT_SUMMED totals, cross-check caveats, shared-wellbore double counting, and the all-or-nothing refusal when a principal is missing. These details materially affect how an agent should interpret and trust the output.

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 purpose is front-loaded and nearly every clause carries specific semantic weight for a complex batch tool. However, the description is one very long run-on sentence, and some phrasing reiterates schema facts like the 25-principal limit and order preservation, making it slightly harder to parse than necessary.

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 complexity, the description covers the critical behavioral edge cases an agent needs: row ordering, missing-principal refusal, unpriced and floor NOT_SUMMED totals, shared-wellbore double counting, and the non-bond nature of the §3.78 floor. The output schema is available for return-value structure, so no further detail is required.

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 parameter is already fully documented, but the description adds meaning by stating that rows preserve request order and that any principal outside the publication causes the entire book to be refused. This goes beyond the schema's syntactic constraints.

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 ('Screens') and resource ('a surety broker's book of up to 25 Railroad Commission of Texas operator numbers'), making the batch-book scope clear. It does not explicitly name or contrast with sibling tools like screen_operators, so sibling differentiation is implicit rather than stated.

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 explains what the tool does but gives no explicit when-to-use guidance, no exclusions, and no alternatives. An agent must infer that this is the batch-screening option versus single-operator siblings from the phrase 'book of up to 25' alone.

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?

Annotations already declare read-only, idempotent, non-destructive, so the bar is lower, and the description still adds real behavioral context: ordering, found:false rows for unpublished operators, empty buckets omitted, the wellbore cross-check explicitly flagged as cosmetic ('changes no outcome, count or cost'), and the §3.78 floor called out as a lower bound rather than a bond amount. Those caveats are exactly the kind of thing an agent cannot infer from annotations.

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 core purpose is front-loaded, but the body is one enormous run-on enumeration of output fields that runs well past what any agent needs before calling. Much of that enumeration duplicates the output schema and buries the genuinely useful caveats mid-sentence.

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?

An output schema exists, so the long field-by-field enumeration is largely redundant effort; the parts that do carry weight (found:false handling, cross-check is informational only, floor is a lower bound) are present. Missing is any indication of cost, rate limits, or when this batch screen is preferable to the single-operator siblings.

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% and the single parameter is documented in the schema (padding, dedupe, bounds), so baseline 3 applies. The description only restates the 200 cap and does not add format or semantic detail beyond 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?

Opens with a specific verb and resource: screens up to 200 RRC operator numbers and returns one row per requested operator in request order. That is clearly distinct from siblings like search_operators or get_well, though the description never explicitly contrasts itself with them.

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?

No when-to-use or when-not-to-use guidance, and no sibling alternatives named despite eight related tools. The only usage-shaped information is incidental ('up to 200 at once', 'found:false rows'), which tells an agent about batching but not about tool 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add behavior beyond that—which it does: a hard 20-result cap, the returned fields, and the sort order (affected count desc, then name). It stops short of noting truncation implications or rate limits, so not a 5.

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, zero filler, with the matching purpose front-loaded and the return shape second. Every clause carries 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?

An output schema exists, so return values needn't be explained, yet the description still summarizes them without bloat. Matching semantics, result cap, and ordering are all covered; only the truncation consequence of the 20-cap goes unstated.

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, but the description adds genuinely new semantics: matching is case-insensitive and substring-based, which the schema's 'Part of the operator name' does not state. The 'up to 20' line also corroborates the limit parameter's maximum.

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 a specific verb and resource ('Finds operators'), the matching rule (substring, case-insensitive) and the data domain (Railroad Commission of Texas). It does not name or contrast with its closest sibling screen_operators, so an agent must infer the boundary between search and screen.

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?

Usage is implied by the substring-matching semantics, but there is no explicit when-to-use, when-not-to-use, or named alternative such as screen_operators or list_operator_wells. The agent has to reason from the name.

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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, and the description adds genuinely new context: verification is against the manifest copy bundled at build time, not a live remote, and it exposes manifest/file URLs so the caller can independently check. It stops short of saying what happens on a hash mismatch (error vs. reported discrepancy).

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 core purpose is front-loaded in the opening clause and every subsequent clause carries real information (data files, index files, URLs, cross-check counts). It is a single very dense sentence, though, and would read better split into two or three.

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?

Return content is well sketched (SHA-256 and byte counts, re-hash of index files, manifest URL, file URL template, cross-check counts) and an output schema exists to carry the structure. The one missing piece is failure semantics – whether a mismatch throws or is returned as data.

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 description notes 'all files, or the given paths', which matches the schema's own 'Omit to report every file' text, so the semantics of the optional array are confirmed rather than added. With 100% schema description coverage the baseline of 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?

Precise verbs (recomputes, reports, re-hashes) paired with specific resources (publication root hash, manifest data files, derived index files) make the integrity-verification role unambiguous. It is clearly distinct from sibling get_publication, though that sibling is never explicitly named as the contrasting read path.

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?

Use is only implied by the word 'verify' – an agent can infer this is for integrity checking rather than data retrieval. There is no explicit statement of when to call it instead of get_publication, and no preconditions or cost guidance.

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