carrier-records

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it excels: it states that no record row is returned, that the answer reflects what the archive holds rather than carrier truth, and clarifies semantic pitfalls (filing on record ≠ coverage in force; absence ≠ finding unless provable). This goes far beyond a simple 'returns info' and preempts misinterpretation.

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 three sentences, front-loaded with the primary action, and every sentence adds essential value—no filler. It efficiently conveys scope, limitations, and interpretive nuances without being 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?

For a tool with two simple parameters and no output schema, the description is remarkably complete. It explains the purpose, the nature of the response, and the correct interpretation of results, covering all the information an agent needs to call it correctly and understand its output. No gaps are apparent.

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 input schema has zero description coverage, so the description must explain both parameters. It does so in the first sentence: 'Qualify a USDOT number and an as-of date' and further contextualizes them. It does not specify date format or validation rules, but it conveys the semantic role of each parameter, which is sufficient given the simple types.

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 action (qualify) and resource (a USDOT number and as-of date), and clearly explains what the tool does: assess whether the archive can answer, what sources hold, and what a purchased record could establish. It differentiates from a retrieval tool by explicitly noting 'It returns no row of the record,' which distinguishes it from siblings that might fetch records, though it does not name those siblings.

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 gives clear context for when to use the tool: when you need to qualify a USDOT number and as-of date regarding archive coverage and potential findings. It does not explicitly mention alternatives or exclusions, but the purpose is explicit enough that an agent can infer the appropriate scenario, earning a 4 rather than a 3.

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 carries the full behavioral burden and handles it exceptionally well. It explicitly warns that the tool returns no record, that it never asserts what was true of the carrier, that a filing is not coverage in force, and that an empty source is not a negative finding unless the answer says the absence is provable. These caveats prevent major misinterpretations of the result.

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 compact and well-structured: the first sentence states the action and outcome, and the following three sentences each add a distinct, necessary caveat. Every sentence earns its place and the key purpose is 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?

The behavioral caveats are thorough, but there is no output schema and no parameter-level descriptions, so the agent is missing the expected date format, docket format, and any concrete example. The description explains what the answer communicates but not the exact shape or syntax needed to make the call.

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 explain both parameters, but it only restates their basic meaning: 'docket number' and 'as-of date'. It provides no format, validation, allowed values, or examples for either string parameter. An agent still lacks the syntax needed to reliably construct a valid input.

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 action ('qualify') and a specific resource (a docket number plus an as-of date), and states what the result covers: archive capability, source holdings, and what a purchased record could establish. It also clarifies that it returns no record row, which helps distinguish it from carrier_record. However, it does not explicitly explain which sibling to choose for what purpose.

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 sentence says when to use this tool versus carrier_record, coverage, specimen, or verify, nor does it name any alternative. The phrase 'whether this archive can answer for them' implies a qualification-before-purchase use case, but that is only implicit. This is effectively no guidance on alternatives or exclusions.

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 must carry the full burden of behavioral disclosure. It only says 'Return,' which implies a read operation, but it does not disclose any side effects, permissions, rate limits, or what happens to the data. The description is too minimal to inform the agent about the tool's behavior beyond the verb.

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, so it is concise in length. However, it uses jargon like 'read surface' and 'how the record is bought' without explanation, making it cryptic rather than clear. It is not front-loaded with useful information that would help an agent understand the tool quickly.

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 no parameters, no output schema, and no annotations, the description is the sole source of context. It fails to explain what the tool does in a clear way, what the output looks like, or when it should be used. The description is too vague for an agent to safely invoke this 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?

The tool has zero parameters and the schema is empty, so there is nothing to explain. The baseline for 0 params is 4, and the description does not conflict with the schema. No parameter information is needed.

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 the verb 'Return' with a resource, but the resource is described as 'the read surface's coverage' and 'how the record is bought,' which are cryptic and ambiguous. It does not clearly state what the tool does or differentiate it from siblings like carrier_record or specimen. The meaning is not immediately understandable.

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 the alternatives. It does not mention any context, prerequisites, or exclusions, leaving the agent without any direction for 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does add meaningful context: the specimen is 'published' and the 'carrier withheld,' indicating it is a controlled sample rather than a full record. However, it does not mention failure behavior (e.g., what happens if the name is not found), any permissions, or the response format. For a simple read operation, the disclosure is partial but not misleading.

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 extremely concise—a single sentence with a clarifying clause. It is front-loaded with the action and includes only essential information. Every word earns its place, with no redundancy or 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 has one required parameter and no output schema, the description should at least explain what the parameter means and what the return value looks like. It does neither. While the purpose is clear, the missing parameter semantics and absence of any output description leave an agent guessing about correct invocation and interpretation. The description is minimally adequate for a trivial retrieval but falls short of completeness.

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 has 0% description coverage, and the description does not mention the 'name' parameter at all. It is unclear whether 'name' refers to the specimen name, carrier name, or something else. The description fails to compensate for the lack of schema documentation, leaving the only parameter ambiguous.

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 specific verb ('Return') and resource ('one published specimen'). It also clarifies the nature of a specimen ('a sample with the carrier withheld, not an issued record'), which distinguishes it from sibling tools like carrier_record that return issued records. This gives a crisp purpose and differentiates it from alternatives.

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 when to use it: when you need a published specimen rather than an issued record. It provides the distinguishing context ('not an issued record') but does not explicitly name sibling alternatives or state when not to use it. While it gives enough context to infer correct usage, it lacks explicit exclusions or 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?

With no annotations, the description carries the full burden of behavioral disclosure. It does disclose some behavioral traits: the answer will not name carrier/customer, will state what the archive holds, and will distinguish filings from coverage. However, it does not state what the tool actually returns, whether it is read-only, what happens on failure, or what 'verify' means operationally. The description is more about answer-interpretation than about tool 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 description is short and front-loaded with the verb phrase, but the remaining sentences are dense and abstract. They are not wasted words, but they are not clearly about the tool's purpose. The structure is acceptable for a short description, but the content is not well organized around what the tool does.

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 single-parameter tool with no output schema and no annotations, the description should clarify what the tool does, what input it expects, and what the output means. It does none of these directly. The epistemic cautions are useful context for interpreting results, but they do not make the tool callable by an agent that does not already know what 'verify' means in this domain.

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 the single 'fingerprint' parameter. It does not explain what a fingerprint is, what format it should take, or how it is used. The description only says 'Verify a Substradium fingerprint,' which adds minimal meaning beyond the schema's 'Fingerprint' title.

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 never states a concrete verb+resource. 'Verify a Substradium fingerprint' is the closest, but the rest of the description is a list of epistemic cautions ('The answer names neither...', 'A filing on record is not coverage in force') rather than a statement of what the tool does. It does not distinguish itself from siblings like carrier_record or coverage, and the name 'verify' is generic.

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 guidance on when to use this tool versus the siblings. The description implies the tool is about verification of fingerprint-derived facts, but it never says 'use this when...' or 'for coverage lookups use coverage instead.' The cautions hint at interpretation rules, but not at selection criteria.

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