mcp-server

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the exact shape of the returned node and its children, plus the default root behavior when id_or_path is omitted. It doesn't mention depth limits or invalid-path error behavior, which keeps it at 4.

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?

Three tight sentences: purpose, return shape, then routing guidance. The behaviorally important detail (omit id_or_path → top concepts) is front-loaded alongside the core purpose.

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 output schema, the description correctly compensates by listing returned fields, and the zero-required-parameter default is made explicit. The remaining gap is the undocumented language parameter and no indication of pagination or traversal depth.

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 only 50%: id_or_path is documented in the schema, but the 'language' parameter has no description anywhere and the description never mentions it, leaving its accepted values and effect undocumented. The description essentially restates the schema's id_or_path text rather than compensating for the gap.

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+resource ('Navigate the PTPGE hierarchy') and enumerates the returned fields (id, notation, label, level, elementType, hasChildren). It also distinguishes itself implicitly from ptpge_search_terms by framing itself as systematic exploration rather than keyword 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?

'Use this for systematic exploration instead of guessing search keywords' gives a clear positive use case and contrasts with search-style siblings, and 'Omit id_or_path to get the three top concepts' defines the entry point. It never names ptpge_search_terms explicitly as the alternative, so there is a small inference step.

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 read-only/idempotent/non-destructive, and the description adds substantial context beyond them: it discloses the exact fetch targets, that it mirrors what a checkout agent sees, that results are validated against published JSON Schemas and the vocabulary, and that 'nothing is stored'. It also describes the return shape (verdict ready|partial|none, one line per step, errors/warnings, missing items with fix locations).

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 verification question is front-loaded and every clause is informative, but the core content is a single long run-on sentence that could be split for scanability. Nothing is redundant, though.

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 output schema, the description carries the return contract itself and does so thoroughly: verdict values, per-step lines, what the agent sees, and what is missing plus where to fix it. For a two-parameter read-only probe this is complete.

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 both parameters are already documented, and the baseline applies. The description explains the fetch paths and the register-driven flow but does not clarify the optional `document` override beyond naming a vendor declaration path, leaving its precedence over the default path implicit.

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 opens with a concrete question ('Does an agent find PTPGE on this domain?') and enumerates exactly what is fetched (.well-known/ucp manifest, ptpge block, declaration.json, vendors register, supplier catalogue). This is clearly distinct from siblings like ptpge_validate_document, which validate a single supplied document rather than probing a live domain.

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 explicit usage contexts: 'is <printer> agent-ready?' and 'why does my declaration not validate?'. It does not explicitly contrast with ptpge_validate_document or ptpge_fingerprint, so the agent must infer which to pick when it already has a document in hand.

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, and the description adds the resolver-hit vs. resolver-miss semantics that annotations cannot express: a lookup against ptpge.org/f/, self-registration within seconds, and status 'unknown' for an unregistered-but-valid fingerprint. That is precisely the extra context the annotations cannot carry.

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 tightly packed sentences, front-loaded with what the tool does and what it returns, then the lookup-vs-inversion caveat and the unknown-status case. Dense with parentheticals but no sentence is filler; a slight readability cost from jargon like 'MIS/ERP' keeps it off a 5.

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 output schema, the description carries the return contract well — it lists the expansion fields and the 'unknown' status path. The only real omission is any guidance on the `language` parameter and the exact shape of a hit vs. miss response.

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 50%: `fingerprint` is documented in the schema and the description restates its accepted forms (ptpge-cfs/1, 64-hex, 16-hex short form, optional resolver URL prefix), which is useful but largely overlapping. The `language` parameter is undocumented in both the schema and the description, so the gap is not compensated.

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 ('expand a fingerprint ... back into its structured configuration') and enumerates the returned structure (matched profile, product, bindings, canonical string, dataset version). It also explicitly distinguishes itself from the inverse operation and from ptpge_fingerprint, so an agent can pick it out of the sibling list 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?

Names the use case ('read-back path for MIS/ERP'), names the alternative that it is not ('not an inversion of the hash'), and ties itself to the sibling that feeds it ('every fingerprint computed by ptpge_fingerprint is self-registered within seconds'). An agent knows both when to call it and what a miss means.

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?

Goes well beyond annotations: discloses that the fingerprint is registered in a public register at ptpge.org/f with the same-configuration→same-entry property and irreversibility, matching readOnlyHint=false and idempotentHint=true. It also explains validation-first issuance and the exact error shape (error=not_fingerprintable + needs_disambiguation), which no annotation conveys.

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?

Front-loads the side effect and irreversibility first, then the computation, then the return shape, then the error contract — a sensible order. It is dense and peppered with spec references (SD-0040, SD-0083, SD-0108) that add length without much decision value for an agent.

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 output schema, the description carries the burden and does: it enumerates both returned profiles, the strict spec ⊂ request containment, the optional visuals payload, and the error/validation contract. An agent has enough to invoke it correctly and handle failures.

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?

Adds real meaning to 'bindings' beyond the schema: every required axis must be bound (or envelope-implied and then written into the identity) and every surface must match a bound setup face. 'visuals' is fully covered by its schema description and is not repeated, which is fine at 67% coverage, but 'product' semantics (URI vs path resolution) remain unelaborated.

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?

Specific verb+resource: 'Compute the canonical ptpge-cfs/1 serialization and SHA-256 fingerprint of a resolved product configuration', with the returned shapes ('spec' and 'request' profiles) spelled out. This distinguishes it clearly from siblings like ptpge_expand_fingerprint and ptpge_validate_config by naming the artifact it produces and its role as quote/order/cache key.

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?

States the context of use (vendor-neutral identity for quoting/ordering/caching) and gives an explicit operational rule for the failure path: on error=not_fingerprintable, put needs_disambiguation questions to the user verbatim and call again; never guess. It never explicitly names an alternative tool (e.g., 'to reverse this, use ptpge_expand_fingerprint'), so sibling routing remains implicit.

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, non-destructive, so the safety profile is covered. The description adds a genuinely valuable semantic rule beyond annotations: 'Absent predicates mean NOT supported (closed semantics)', which prevents misinterpretation of missing fields. It does not describe the return shape in detail, but that is the only remaining gap.

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?

Three tight sentences, front-loaded with the core action and payload contents, followed by the usage routing and the closed-semantics caveat. Zero filler.

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 output schema, the description usefully summarizes what is returned and, critically, explains how to interpret absent predicates. Only the undocumented 'language' parameter is left unaddressed, a minor gap for a simple two-parameter read 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?

Schema description coverage is 50%: id_or_path is documented in the schema, but the 'language' parameter has no description in either place. The description adds no parameter-level guidance (e.g., what form the id_or_path takes or what language affects), so it neither compensates for nor repeats 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?

Specific verb and resource: 'Return the complete Configuration Envelope of a product class in one call', and it enumerates the payload (supportsSetupModel, perSurfaceSupports* predicates with resolved labels, typical* descriptors). It is clearly distinguishable from the granular ptpge_get_term 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?

Explicitly states when to use it ('use it before composing a configuration') and names the alternative it replaces ('instead of many individual ptpge_get_term calls'). The routing decision is fully specified.

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=true, idempotentHint=true, and destructiveHint=false, so safety is covered structurally. The description adds useful context by listing what content is returned and what input forms are accepted, but says nothing about behavior for unknown terms (error vs empty) or response size/pagination.

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 compact sentences, front-loaded with the core action and followed by the input-form note. No filler or repeated 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?

With no output schema, the description carries the burden of describing return values, and it does so by enumerating the term facets. The main remaining gap is undefined behavior on a missing term, which would help an agent handle failure.

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 both parameters are already documented, and the description largely restates the schema's URI-or-relative-path rule. It does reinforce the accepted alternates, but adds no new semantics such as path normalization or language fallback behavior.

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 ("Fetch full context for a single PTPGE term") and enumerates the returned facets: definition, relations, mappings, properties, notation, level, metadata. It implicitly separates itself from ptpge_search_terms by emphasizing a single term, but never names the sibling 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 "for a single PTPGE term" implies when to use this over search_terms or browse, but no explicit when-to-use/when-not guidance or prerequisite (e.g., needing a known id) is given. The agent must infer the selection criteria.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds value beyond that by itemizing what the response contains, which matters because no output schema exists. It does not mention cost, caching, or whether the version string format is stable, keeping it out of 5 territory.

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. The returned fields lead, and the use cases follow, so an agent gets the payload description before the framing. Nothing is repeated from the title or annotations.

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 input parameters and no output schema, the description's job is to say what comes back and why you'd want it, and it does exactly that by listing every returned field plus three valid use cases. An agent has everything needed to decide to call it and to interpret the response shape.

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 there is nothing to disambiguate and the baseline of 4 applies. The description correctly adds no parameter talk, which is appropriate rather than a gap.

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 ("Return") and resource ("the current PTPGE dataset version") and then enumerates the exact payload: term count, per-level and per-group counts, license, scheme URL, server version. That is unmistakably distinct from sibling tools like ptpge_browse or ptpge_search_terms, which operate on terms rather than metadata.

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?

Names three concrete situations (version-pinning, health checks, diagnostics), which gives an agent a real decision rule for reaching for this tool. It stops short of explicitly excluding alternatives or saying when not to call it, so it lands at 4 rather than 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?

Although annotations already declare readOnly/idempotent/non-destructive, the description adds substantial context the annotations cannot: three possible outcome shapes, the resolution mechanism via the product envelope's colorChannelCount, and a hard behavioral rule against inferring ambiguous answers. The '1 is black on some products and a named spot colour on others' warning explains exactly why guessing is dangerous.

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?

Purpose and the critical semantic correction are front-loaded, followed by outcome enumeration and then the hard warning. Every sentence carries operational weight; capitalization is used sparingly for the two genuinely failure-prone points.

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 output schema, the description carries the burden of describing returns and does so at the level of three outcome variants, which is enough to act on. The internal shape of a deterministic binding and what 'invalid_for_template' implies for next steps are left 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 80%, so baseline is 3; the description nevertheless adds real meaning by reinterpreting 'notation' as a separation count resolved against envelope-supported combinations rather than a colour code. It does not expand on 'setup', 'surfaces', or 'language' beyond what the schema already says, so not a 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?

States a specific verb ('resolve') and resource ('print colour pair notation into per-surface colour bindings for a given product'), and immediately clarifies the non-obvious semantics of the notation token. This is clearly distinct from siblings like ptpge_fingerprint or ptpge_validate_config.

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?

Gives a strong conditional rule for the disambiguation path ('you MUST put its question to the user') and an implicit ordering constraint relative to fingerprinting ('Do not fingerprint an unresolved configuration'). It does not name sibling tools or state exclusions explicitly, so it stops short of 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 cover read-only/idempotent/safe behavior, and the description adds real value: a ranked result set with a 0.0–1.0 relevance score and the enumerated level taxonomy. It does not mention pagination, but the depth of return context exceeds annotation coverage.

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 verb+resource, then a compact enumeration of return shape. Dense but efficient; the only mild bloat is the long field list in sentence two.

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 output schema, the description compensates by listing the return fields and relevance scale. For a read-only search tool with full schema coverage, this is near-complete; only pagination/empty-result behavior is 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 description coverage is 100%, including the nuanced query_language vs language distinction, so the schema carries parameter meaning. The description only gestures at returned fields (level, group, URI) and adds nothing beyond what the schema already documents.

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 ('free-text search') and resource ('PTPGE vocabulary and registers'), plus the domain gloss 'the open specification of print'. It implicitly separates from siblings like ptpge_get_term (URI lookup) and ptpge_browse (navigation) by framing this as free-text ranked search, though it never names 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?

The word 'free-text' signals when this applies versus exact lookups, but there is no explicit when-to-use/when-not or reference to ptpge_browse or ptpge_get_term as alternatives. Guidance is implied rather than stated.

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?

Goes far beyond the annotations: it discloses returned fields (alsoOfferedBy, switchHint, advisories, complete), the needs_disambiguation elicitation contract ('never infer the answer'), completeness checks for missing required axes, surface-face rejection behavior, and spot-ink binding rules. The readOnly/idempotent/non-destructive hints are already in annotations, so this extra context is pure added value.

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?

Purpose is front-loaded, which is good, but the description is a dense wall of specification detail with internal references (SD-0083, SD-0104) and a long URI-construction example. The shared elicitation contract is boilerplate repeated across ptpge_* tools. All content is relevant, but it could be structured more scannably.

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 output schema, the description carries the full burden and does so: it explains what needs_disambiguation contains, what complete:true means, what alsoOfferedBy/switchHint are for, and what advisories represent. An agent has enough to interpret outputs and follow the elicitation contract without further documentation.

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 67%, and the description compensates well for the bindings parameter: it explains surface-face validity (flat-sheet front/back, folded-sheet outside/inside, etc.), spot-ink value construction with concrete URI examples (Pantone 300 C → …/pantone-matching-system/300-c), and cardinality rules for multi-value variables. The `product` and `language` parameters get no additional treatment in the description, leaving a small gap.

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 — 'Envelope validation of a product configuration against the specification' — and immediately defines what is checked (every binding against the product's supports* envelopes). This is clearly distinguishable from siblings like ptpge_validate_document or ptpge_check_domain, which have different scopes.

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 routes behavior: when a value is not in the envelope but another template accepts it, 'switch product and validate again' rather than dropping the buyer's request. It also names exclusions — cross-variable legality and vendor capability matching are 'an implementation's concern, not the specification's', and commercial values belong to the transaction layer.

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?

Goes well past the annotations by disclosing that nothing is fetched from any domain and nothing is stored, that deprecated terms only warn, and that fingerprints are recomputed and compared against stated values including the SD-0108 quote rule. It also states the return shape (valid, errors[], warnings[], what was checked), which is valuable since no output schema exists.

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 action and scope are front-loaded and there is no filler; the two trailing sentences carry distinct, non-redundant information. The middle sentence is dense with stacked parentheticals, which slows parsing slightly but is not wasteful.

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 validator with no output schema, the description covers inputs, validation layers, side effects (none), and return contents. An agent has everything needed to decide to call it and to interpret the result.

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?

With only one parameter at 100% schema coverage the baseline is high, and the description still adds real semantics: the document is a JSON object whose `schema` field determines which validation path applies, and for request/1 and quote/1 the document must carry fingerprints derived from the configuration. It does not describe the internal shape of the document object, but that is delegated to the published schemas.

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?

Names a specific verb (validate) and a scoped resource (ONE document), enumerates the document types it accepts (vendor declaration, supplier catalogue, request, quote, UCP manifest) and the three conformance layers it applies (JSON Schema, vocabulary, identity). The 'ONE document' framing and the document-vs-configuration focus implicitly separate it from the ptpge_validate_config 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?

States the context clearly: it is the PTPGE Ready conformance check for a module that writes these documents, so an agent knows to call it on outbound documents. It still never names an explicit alternative (e.g. use ptpge_validate_config for configurations, ptpge_fingerprint for raw fingerprinting) or a when-not-to-use case.

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