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

Beyond readOnlyHint/destructiveHint, the description discloses substantial behavior: the output is a signed JWS, links are pairwise pseudonyms and never real ids or names, it is valid at most 15 minutes, and it must be verified against the tenant JWKS endpoint. It does not say what happens when the requested token/doc has no lineage or how the call fails.

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 dense sentences with no filler, front-loaded with what the artifact is, followed by the operational details (verification URL, expiry). The JWKS path adds length but is load-bearing 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 shape need not be explained. However, for a 5-parameter tool with a required audience and two alternative identification paths, the description never says whether token_id and doc_id/version are mutually exclusive or how to choose between them, leaving a meaningful selection gap.

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 carries the burden and largely meets it: audience is "one audience" scoping, ttl_seconds is bounded by the stated 15-minute maximum, and the doc_id/version vs token_id distinction maps to "the token that wrote a document version" vs "who issued a token." The mutual exclusivity between those two id paths is left unstated.

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 the resource precisely: a signed JWS proving token issuance lineage (or the token that wrote a document version) and the grants on each link, scoped to one audience. That distinguishes it from the plain get_lineage sibling, though the retrieval verb itself is only implied by the name rather than stated ("Returns/gets...").

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: you fetch this when you need an audience-scoped, verifiable proof. The verification recipe (jwks.json path) and the 15-minute validity window are practical guidance, but there is no explicit when-to-use/when-not and no named alternative such as get_lineage or explain_write.

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