inspect_credential_offer

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

With no annotations, the description must carry behavioral burden. It does disclose useful behavior: it resolves the offer 'by value or by reference' and returns specific data. But it says nothing about validation failure modes, networking behavior, or side effects, which matters for a resolve/validate operation.

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 with no filler. The main action is front-loaded, and the second sentence adds the behavioral and output details an agent needs. Every sentence 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?

The tool has only one parameter and an output schema, so the return shape is already covered. The description adds the key resolution distinction and output highlights. Minor gaps are validation behavior and explicit exclusions, but overall an agent can invoke this correctly with the information provided.

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 credential_offer is a string. The description compensates by explaining it is a Credential Offer URI and that it can be resolved by value or by reference, giving the agent meaningful semantic context for the sole parameter beyond the raw type.

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 specific verb and resource ('Parse and validate an OIDC4VCI Credential Offer URI') and then lists the concrete outputs (Credential Issuer, configuration IDs, grants). This makes it clearly distinct from the sibling issuance-and-status tools, which focus on different stages of the protocol.

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 intended trigger is inferrable: an agent should use this when it has an OIDC4VCI Credential Offer URI to inspect. However, the description never explicitly says when to prefer this over siblings or when not to use it, so the usage 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.