Tool Discovery & Tool Calls

8 min

From Question to Verified Answer

Suppose a user asks: "Which faculty work on agentic AI?" Here is the whole journey in 10 steps. The rest of this module zooms in on each stage.

Key takeaway: A tool call is a chain of small steps, and a person opens and closes it.

10 min

Tool Discovery: tools/list

Before an AI can use a tool, it has to know the tool exists. The client asks the server "what tools do you have?" using a request named tools/list. The server answers with a description of each tool.

{
  "tools": [
    {
      "name": "find_research_experts",
      "description": "Find people by research topic and role.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "topic": { "type": "string" },
          "role": { "type": "string", "enum": ["faculty", "student", "staff"] }
        },
        "required": ["topic"]
      }
    }
  ]
}

• name: what the tool is called
• description: what the tool is for, in words the AI can read
• inputSchema: which inputs are allowed and which are required (here, topic is required)

Key takeaway: tools/list is how a tool introduces itself: name, purpose and allowed inputs.

10 min

Selecting a Tool and Preparing Arguments

With the tool descriptions in hand, the AI matches the question to a capability and fills in the schema. For "Which faculty work on agentic AI?", the description of find_research_experts fits, and the boxes get these values.

Key takeaway: Check the visible tool choice and the visible arguments, not an imagined thought process.

12 min

Tool Invocation: tools/call

To run the tool, the client sends a request named tools/call, with the tool name and the arguments. Before running anything, the server validates the arguments against the schema. If a required value is missing or a value is not allowed, the call is rejected instead of guessed.

{
  "method": "tools/call",
  "params": {
    "name": "find_research_experts",
    "arguments": {
      "topic": "agentic AI",
      "role": "faculty"
    }
  }
}

1. 1Send
   The client sends the tool name and the arguments.
2. 2Validate
   The server checks the arguments against the schema.
3. 3Execute
   If valid, the server runs the tool against the authoritative data.
4. 4Reject
   If invalid, the server returns an error the AI can act on, such as fixing the missing value.

Key takeaway: tools/call sends a name and arguments; the server validates first and rejects instead of guessing.

10 min

A Structured Result with Provenance

The tool returns a structured result: fields the AI and the interface can read reliably. A good result also carries provenance, which says where the data came from and how fresh it is.

{
  "results": [
    { "name": "Example Person A", "role": "faculty", "topics": ["agentic AI"] },
    { "name": "Example Person B", "role": "faculty", "topics": ["agentic AI", "learning analytics"] }
  ],
  "provenance": {
    "source": "AI4X research directory",
    "retrievedAt": "2026-01-15T09:00:00Z",
    "lastUpdated": "2026-01-10",
    "completeness": "partial"
  }
}

Key takeaway: A result is only as useful as its provenance: source, freshness and completeness.

10 min

Grounded Answer and Human Verification

The AI now writes its answer from the tool result. A grounded answer keeps two things apart: facts that came from the tool, and the AI's own wording or summary around them.

The last step is yours. Check the names against the source, look at the date, and decide whether the answer is good enough for what you will use it for.

Key takeaway: Ground the answer in the result, report gaps honestly, and let a human verify.