Audit Your Agent's Tools and Skills Into a Trustworthy Capability Contract

The magic box is a UX failure

Agent UX dies when the product asks users to trust a black box. The model may be capable, but the interface still hides what the agent can do, what it may change, and what happens when it cannot finish. That is not a model problem first. It is a contract problem.

The useful pattern is simple: make capabilities, permissions, and failure modes explicit as inspectable contracts. A trustworthy agent does not announce itself as powerful. It shows its scope, its limits, and the evidence that it stayed inside them.

Do not design an agent as a promise. Design it as a receipt.

Users are not asking for more magic. They are asking for a way to verify that the agent did what it said it could do. That is the core of capability disclosure in agent products.

What the reference gets right

A tool reference offers a useful model for this kind of disclosure. It distinguishes tools from skills, defining tools as callable endpoints and skills as reusable instruction packages.

The reference preserves exposed tool descriptions and TypeScript declarations, giving a record of what is exposed.

Availability can change with session configuration, permissions, connected apps, and installed plugins, making it a variable condition.

These disclosures need a place in the product's public documentation.

Every available skill has its own page containing a verbatim copy of its main definition, making the definition available to check.

Audit your agent into a capability contract

Use the reference as a checklist, not a template. Your product may have different tools, different skills, and different risk levels. The goal is to turn the hidden architecture into a contract that users can inspect and that your team can maintain.

1. Classify tools and skills. List every direct action the agent can invoke as a tool. List every reusable set of instructions as a skill. If a capability is both a function and a policy, split it. The user should be able to see what the agent can call and how it is allowed to use it.
2. Expose declarations and descriptions. For each tool, publish the description, input shape, output shape, and any relevant type information. For each skill, publish the core instructions in plain language. If the declaration changes, the user-visible copy should change too.
3. State availability conditions. Do not show a tool as available unless it is available in the current context. Make the conditions explicit: what the user must enable, connect, or configure. If a tool is unavailable, say why and what would make it available.
4. Document failure modes. For every high-risk capability, describe what happens when the request is denied, the output is incomplete, the tool times out, or the skill cannot be applied. A failure mode is not an error message. It is a designed outcome.
5. Surface user-visible receipts. After the agent acts, show what was called, what permission was used, what was changed, and what was left untouched. The receipt should be short enough to scan and detailed enough to verify.

The contract should live where users can find it, not buried in a settings page. It should be readable by a product designer, a support agent, and a skeptical user. If the contract is only useful to engineers, it is not a trust surface yet.

Start with the capabilities that can cause the most harm or the most confusion. A tool that edits files, sends messages, spends money, or changes permissions needs a stronger contract than a tool that summarizes text. The more irreversible the action, the more explicit the disclosure should be.

End with a simple test: can a user look at the agent's capability contract and predict what it will do next? If the answer is no, the interface is still asking for faith. If the answer is yes, you have moved from a magic box to a trustworthy product.