Tool Calling

A large language model can generate information only. To let it read a file, search the web, or run a command, the application supplies a set of structured Tools. The model returns which Tool it wants to call and with which parameters; the application executes the call only after validation.

A Tool is not a natural-language incantation

Every Tool has a name, purpose, and parameter schema. If the model writes “I modified the file,” no file changes. An action is evidenced only when an actual file Tool runs and returns a successful result.

Similarly, a model claim such as “the user authorized this” inside a parameter has no effect. Permissions come from settings stored by the application and the current Run; approval comes from your explicit action.

Common Tool categories in Captain Who

• Files and code: list, search, read, write, and apply patches.
• Commands and sessions: run managed commands and track long-running tasks.
• Git: inspect workspace diffs.
• Network: Tavily search and webpage reading.
• Documents and artifacts: process Word documents, spreadsheets, presentations, PDFs, and images.
• Skills: activate instruction packages, read resources, or run controlled scripts.
• MCP: call a third-party Tool connected by the user or a built-in browser capability.
• Collaboration: create, wake, observe, and coordinate subagents.
• Scheduled Automation: a scheduled Run can record results in run history.

The Tools actually visible to a task vary with permissions, configuration, selected Skills, MCP connections, and runtime context. The fact that the application implements a Tool does not guarantee that the current task can use it.

Permissions and approvals are different

Permissions determine whether a category of action may enter the execution path. Approval determines whether a specific action needs your confirmation. Even with automatic approval, path validation, command-risk policy, and Tool-identity checks still apply.

Default permissions suit most first-time tasks. Full access expands read, write, and command scope and should be used only briefly when you understand the project and task. Custom permissions separately control read scope, write scope, command approval, and structured file-modification approval.

What to inspect in an approval

1. Does the Tool and its source match the task?
2. Is the file path, command, or target site correct?
3. Is the effect read-only, reversible, or capable of producing an external side effect?
4. Does it contain credentials, personal data, or information that should not be sent?
5. What scope would Don't ask again for this turn relax?

Rejection is not an error. Include a direction for adjustment and have the Agent use a narrower file scope, a read-only command, or another method.

Why results may be truncated

Command output, webpages, and MCP results can be very large. The system limits content entering the model and interface, using pagination, previews, or a separate Artifact when needed so one Tool does not consume the entire context window. When you see Truncated, have the Agent narrow the query or read the next segment instead of assuming that omitted content is irrelevant.

Outcome unknown

When an external action may have been sent but its response is lost through a timeout, cancellation, or process failure, the status is Outcome unknown. This is not an ordinary failure: the action may have succeeded or failed. Inspect the target system before deciding whether to compensate or retry.

Start with the practical tutorial Implement a small feature. For safety guidance, see Use Agents safely.