Chapter C59 · Interactive Course
Inspect, connect and troubleshoot
Narrow scope, provenance, manual inspection, selection and layers.
Core Learning Concept
Debug the supplied connector one layer at a time. Confirm the intended operation and package origin, then inspect reachability, protocol support, credentials, arguments, and results. Use a narrow harmless probe where appropriate. A successful probe establishes its own conditions, not every permission or future operation.
What You’ll Learn in This Chapter
-
Start with a narrow capability
Define one useful operation before connecting a server.
Define one useful operation and its expected result before adding a broad connection. “Read available appointment times” identifies a narrower need than “connect the calendar.” That requirement guides tool choice and permissions. Start with a small probe you can inspect before extending the workflow.
-
Verify the server’s origin
Identify the exact project and endpoint being configured.
Verify a server’s publisher, exact package or endpoint, version, and source through trustworthy documentation. Similar names can refer to different software. A registry entry helps locate a package but does not replace checking identity and capabilities. Inspect what will actually run or receive data.
-
Inspect a server independently
Separate protocol checks from the model choosing a tool.
An independent protocol client or inspector can test a server without model selection in the loop. A successful narrow call helps isolate the failure, but proves only that operation under those credentials and conditions. If the app still fails, compare its exposure, inputs, policy, and environment with the successful probe.
-
Large catalogs need selection
Explain why relevant tools should be discoverable without overwhelming context.
A large capability catalog can add selection and context costs. Hosts may expose a subset or discover tools on demand. Make the required capability easy to find with clear descriptions and supported selection mechanisms. Measure behavior before assuming that simply exposing every tool improves the agent’s usefulness.
-
Untrusted output stays data
Recognize instructions embedded in a retrieved result.
Tool output and retrieved documents are task material even when they contain instruction-shaped text. A demand to change the user’s goal or disclose unrelated information should not gain authority merely by appearing in a result. Keep the task boundary and enforce access controls in the surrounding system.
-
Diagnose the failing layer
Choose a next check using a connection trace.
Isolate connector failures methodically: reachability, protocol negotiation, authentication, argument validation, and tool execution. Fix the earliest error layer first, then rerun targeted probes to confirm that all subsequent pipeline stages succeed reliably.
-
Debug the supplied connector
Use an offline Inspector transcript to distinguish a bad endpoint, missing permission and poor tool description, and propose one specific repair for each.