postalref

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real value beyond them by disclosing the shape of the result: layout, per-field digits and meaning, check-digit verdict, service type code row, each with supporting passage.

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?

One front-loaded sentence with no filler, though it is a long compound clause listing output components. Every element listed is content-bearing, so the density is justified.

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 read-only decode tool with an output schema and full annotation coverage, the description gives enough to call it correctly and set result expectations. Only input-format edge cases remain unaddressed.

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 0% and the schema only says 'string, maxLength 80'. The description compensates partly by identifying the accepted value as an IMpb package barcode or tracking number, but it never states character rules, acceptable lengths, or what happens with a malformed 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 states a specific verb+resource: reading a package barcode/tracking number (IMpb) to decode its layout and fields. That is clearly distinct from siblings like diff, define, or search, though no sibling is named 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?

The usage is implied by 'Read a package barcode or tracking number (IMpb)' – an agent can infer it is for exactly one barcode string. However, there is no explicit when-to-use guidance, no exclusions (e.g. non-IMpb barcodes), and no routing to alternatives such as lookup or search.

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, so the safety profile needs no restating. The description does add value by enumerating what a result entry contains (USPS definition words, page, other names, postalref note, postalref page), which is the main behavioral disclosure. It says nothing about matching behavior (exact vs. fuzzy), what happens on a miss, or ordering, which would matter for a lookup tool.

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, front-loaded with the core question it answers, and no redundant restatement of the title or annotations. The dense enumeration of return contents is earned because it explains what 'define' yields in this registry.

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 rich annotations, an output schema, and full schema coverage, the description only needs to establish what the tool does and what a result broadly contains — both are covered. The remaining gap is behavioral matching rules, but that is a minor omission given the structured data already present.

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 both parameters are documented, including examples (mailer id, MID, CRID) and the default limit of 5, so the baseline is 3. The description's only semantic contribution is the plural 'each registry entry it names', which implies that one name may map to multiple entries and thus justifies the limit parameter — a modest but real addition.

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 precisely what the tool returns for a USPS term: registry entries with USPS definitions, page references, alternate names, and postalref explanations. It is immediately clear this is a terminology-definition lookup rather than a search or document reader. It stops short of naming which sibling (decode, lookup, search) it displaces, so sibling differentiation is left implicit.

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 guidance, and none of the six siblings (decode, lookup, search, search_documents, read_source, diff) are referenced. An agent must infer from the wording that this is the definitional lookup versus broader search. The phrase 'each registry entry it names' hints at multi-entry behavior but is not framed as a usage rule.

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, so the safety profile is covered. The description adds useful context about the shape of what comes back (per-code deltas, per-section deltas, severity ratings, attribution), but says nothing about pagination/limit behavior, defaults, or cost, so it is a modest add rather than a rich one.

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?

One compact sentence that front-loads the core question ('what changed ... between two editions') and then enumerates the return content. Slightly dense in the trailing clause, but every element earns its place and nothing is redundant.

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 a complete input schema, an output schema, and full annotations, the description only needs to convey intent and return shape, which it does. The remaining gap is the absence of guidance on when to reach for this versus read_source or search_documents.

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%, so all six parameters (including the from/to/limit defaults and the severity enum) are already documented in the schema. The description adds no syntax, format, or edge-case detail beyond that, which is the baseline-3 case.

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-equivalent (compare editions) plus the two resource types it operates on (code table or document) and enumerates exactly what the result contains: added/removed/changed codes, changed sections, severity ratings, and rater. That level of specificity makes it trivially distinguishable from siblings like lookup, define, or read_source.

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 wording ('between two editions'), but there is no explicit when-to-use, when-not, or pointer to an alternative such as read_source for a single edition or search for locating a subject. An agent must infer that this is the comparison tool rather than the retrieval tool.

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, closed-world, and non-destructive, so safety is covered. The description adds real behavioral detail beyond that: results are drawn from the newest edition listing the code, alternate editions and history are included, and every row carries a passage id. It stops short of noting result size or ordering 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?

A single dense sentence, front-loaded with the verb and resource, then the return payload. Every clause carries information; nothing is redundant with the title or schema.

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 and full parameter documentation, the description only needs to frame intent and behavior, which it does. The gap is the absence of routing guidance among the six sibling tools for what appears to be a core entry point.

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%, so both 'code' (format examples 055, 920, PM, 01) and 'table' (enumerated table names, all tables when absent) are fully documented structurally. The description adds the notion of 'newest edition' but no additional parameter-level semantics, so the 3 baseline holds.

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 ('Look up a USPS code') and enumerates the payload returned (the printed row, named codes, listing editions, history, passage ids). What it does is unambiguous, but it never distinguishes itself from sibling tools like decode or define, which plausibly operate on the same codes.

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 statement of when to use this instead of decode, define, diff, or search. The only scoping hint is inherited from the schema's 'table' parameter, not from the description, so an agent must infer that lookup is the by-code entry point and search is the free-text one.

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 readOnly/idempotent/non-destructive, so the description's added value is the 'as extracted' caveat (text may be extraction artifacts) and the citation contract requiring sha256 plus PDF page plus exact words. That is real behavioral context an agent needs before quoting. It stops short of describing pagination limits or error behavior, though the schema covers page/pages.

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 front-loaded sentence with no filler, but the dense colon-chained clause about quoting makes it slower to parse 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 and annotations carrying the safety profile, the description only needs to convey intent and the extraction/citation contract, which it does. Minor gaps around behavior for invalid documents or empty find results are handled by the schema and output schema rather than the prose.

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%, with defaults, ranges and find/page interaction all documented in the schema. The description only reinforces the citation use of revision sha256 and page numbering, adding little beyond structured fields, so the 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 (Read) and resource (a revision of a modeled USPS document) with the scoping detail 'page by page, as extracted, to quote it'. That framing separates it from search-style siblings like search_documents, but it never names an alternative 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?

The phrase 'to quote it' implies the tool's purpose (retrieving verbatim text for citation) and the citation contract hints at how to use results. There is no explicit guidance on when to prefer this over search_documents or lookup, and no stated 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds two genuine behavioral facts beyond that — result ordering favors exact names/codes, and long digit strings are treated as a single decode target — though both are stated ambiguously enough to leave the agent guessing at actual 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?

Two sentences is a good size and the verb is front-loaded, but the second clause is syntactically tangled ("postalref models, exact names and codes first"), costing clarity rather than saving space.

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 and full annotations carry much of the load, so return format and safety need not be described. Still, for a search tool sitting among five competing siblings, the description does not give the agent enough to route confidently.

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 schema's own example ("055, mailer id, ground advantage") explains the query parameter better than the description does. The description adds no syntax, format, or limit guidance, so the 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?

It states a verb ("Search") and the resources searched (codes, terms, specs, documents), so the general purpose is recoverable. But the phrasing "postalref models, exact names and codes first" is garbled and never cleanly distinguishes this tool from siblings like lookup, define, or search_documents.

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 guidance and no named alternative. The only routing signal is indirect — "a query of 20 or more digits comes back as one to decode" implies the decode sibling exists but never says to call it instead.

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, closed-world behavior. Beyond that, the description adds useful traits: the search covers *every* document, results include page and newest file, and a subset of results is slug-tagged for follow-up. It does not discuss pagination or match-ranking, but with annotations covering the safety profile this is a meaningful addition.

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, front-loaded with the core purpose and no wasted words. The follow-up slug note is compact and 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?

With a complete schema, full annotations, and an output schema, the description only needs to orient the agent, which it does. The one shortfall is the missing contrast with the 'search' sibling and any hint about result ordering or matching behavior.

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%, with all three parameters described, including the topic enum. The description implies the query targets title/file name but adds no format or matching semantics beyond the schema. Baseline 3 is appropriate.

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 ('search') and resource ('every document on PostalPro') with scope qualifiers (by title and file name). It differentiates from read_source by noting that some results carry a slug, but it does not distinguish itself from the sibling tool named 'search'.

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?

Provides a clear routing hint: documents modeled by postalref carry a slug for read_source, implying when to follow up elsewhere. It does not define explicit when-not conditions or contrast with the generic 'search' sibling, leaving a gap.

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