Skip to content
ContractSpec
Start here

Core guide · Operations · 3 min read

Find the boundary that failed

Diagnose package, schema, execution and transport failures without changing several layers at once.

Source context

Source-guided · d58fa5b7

Repository links may require access. Source inspection is separate from a clean public-package installation.

AN INTERACTIVE READING MAP

Get the shape of this guide.

Move through the ideas, inspect their relationships, or make a focused reading path. The complete guide stays below.

READING SEQUENCE

Understand how the ideas connect

01 / READING POINT

Capture a small reproducible case

Record the package versions or commit, operation key and version, chosen adapter and sanitized request. Keep the first relevant error and trace identifier. Start from the boundary where the failure appears instead of reinstalling or regenerating the entire project.

Remove provider credentials and personal data from a reproduction. A fixture subject and a disposable handler are usually enough to isolate schema, registry or approval behavior.

1 / 4

0 points in your packet

Capture a small reproducible case

Record the package versions or commit, operation key and version, chosen adapter and sanitized request. Keep the first relevant error and trace identifier. Start from the boundary where the failure appears instead of reinstalling or regenerating the entire project.

Remove provider credentials and personal data from a reproduction. A fixture subject and a disposable handler are usually enough to isolate schema, registry or approval behavior.

Use the symptom to choose the next check

A request can fail before the handler, inside business logic or after the handler returns. Distinguishing those points prevents changes that make the interface appear fixed while hiding the real issue.

SymptomCheck firstAvoid assuming
Package cannot be resolvedSelected registry, exact package version and public exportsA workspace path is a published import
Spec or handler missingRegistration, key/version and bindingA declaration executes merely because it exists
VALIDATION_FAILEDDeclared input and adapter input mappingA policy rejection caused the failure
UNAUTHENTICATEDTrusted adapter contextA role field in input authenticates the caller
APPROVAL_REQUIREDRequirement, receipt and approval portAny token-shaped value authorizes a request
Invalid outputHandler return value and output modelThe failed response rolled back earlier effects
API works, MCP failsTool schema, identity and result handlingBoth transports have identical wire semantics

Isolate one layer at a time

First confirm the operation is registered and bound. Then test the registry with the same valid input and a deliberately constructed fixture context. Finally invoke the actual adapter. This tells you whether the problem is in the handler or in transport/context mapping.

For approval failures, inspect the reason. Missing evidence and a missing approval runtime require different fixes. Keep the fail-closed behavior while correcting the host configuration.

Check documentation provenance

If a copied snippet refers to a different metadata shape, import path or command flag, compare it with the selected version's source. The source-guided pages here deliberately identify their snapshot so differences can be examined.

When reporting a docs defect, include the page URL, package version, smallest failing snippet and expected result. That is more actionable than a screenshot of a large terminal log.

Read the signal at the stage it describes.

A trace can help explain a request, but timing and durability determine what it establishes.

Which signal are you looking at?

A CONCRETE SITUATION

The boundary stopped the operation before the effect.

The result reports a meaningful failure before handler entry.

01 / Identify

Carry operation key, version and trace context.

What changes

The operation identity and failure category show where to investigate.

What stays explicit

A precondition denial is different from a business failure after execution began.

Follow the consequence

Fix the applicable input or trusted context, or follow the authorized approval path. Preserve that distinction in the explanation.

An authored situation, grounded in the linked source guides. Choosing a case explores its expected responsibilities; it does not execute an operation.