Tools JSON Schema Analysis
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Tools JSON Schema Analysis provides a comprehensive breakdown of the functional interfaces used by various AI agents (Cursor, Lovable, Trae, and Amp) to interact with their environment. These schemas define the structure of tool calls, ensuring that agentic models provide necessary parameters such as absolute file paths, replacement strings, and shell commands in a format the system can parse and execute.
The scope of this analysis covers the core architectural patterns of tool definitions, including file system operations, terminal execution, and specialized agent-to-agent communication. These schemas facilitate a "loop" where the agent analyzes a state, selects a tool based on its JSON definition, and receives an observation based on the execution of that tool.
Sources: Amp/gpt-5.yaml:268-271, Manus Agent Tools & Prompt/Modules.txt:28-36
Core Tool Architecture
The tools in this project follow the standard JSON Schema specification (Draft 2020-12 in some cases) to describe the interface between the AI model and the underlying operating system or IDE. Each tool is defined by a name, a description that provides the model with usage context, and a parameters (or input_schema) object defining the required data types and constraints.
Tool Definition Structure
A typical tool definition includes mandatory fields that enforce strict adherence to the execution environment's requirements, such as requiring absolute paths for Windows or Unix environments.
The diagram above illustrates the relationship between a tool's identity and its functional constraints as defined in the source schemas.
Sources: Amp/gpt-5.yaml:398-405, Amp/claude-4-sonnet.yaml:498-505
File System Interaction Schemas
File manipulation tools are the most complex schemas, often requiring multi-part strings for replacements or specific line ranges for reading.
Read Operations
Read tools like Read or read_file use schemas that allow for pagination or windowed viewing of large files to prevent context window overflow.
| Parameter | Type | Description |
|---|---|---|
path | string | The absolute path to the file. |
read_range | array [number, number] | 1-indexed start and end line numbers. Defaults to [1, 1000]. |
Sources: Amp/gpt-5.yaml:705-725, Amp/claude-4-sonnet.yaml:810-830
Edit and Search-Replace Operations
The edit_file tool uses an old_str and new_str pattern. This requires the agent to find an exact match within the file to apply a change.
The flow above describes the logic enforced by the edit_file schema, where a failure to match the old_str exactly results in a failed execution.
Sources: Amp/gpt-5.yaml:438-460, Amp/claude-4-sonnet.yaml:530-555
Terminal and Command Execution
The Bash tool (or run_in_terminal) provides a direct interface to the shell. Its schema includes safety and context parameters like cwd (Current Working Directory).
Bash Tool Schema Parameters
| Field | Type | Required | Description |
|---|---|---|---|
cmd | string | Yes | The shell command to execute. |
cwd | string | No | Absolute path for execution directory. |
Sources: Amp/gpt-5.yaml:370-385, Amp/claude-4-sonnet.yaml:460-475
Specialized Agent Orchestration
Several tools (e.g., Task, Oracle, codebase_search_agent) act as interfaces to sub-agents. These schemas are "recursive" in nature, passing a prompt to a new agent instance.
Task Tool Logic
The Task tool schema requires a prompt and a description. This allows a "senior" agent to delegate a multi-file implementation to a "junior" agent with its own set of tool constraints.
This sequence shows the delegation flow defined in the orchestrator tool schemas.
Sources: Amp/gpt-5.yaml:840-865, Amp/claude-4-sonnet.yaml:940-965
Technical Constraints and Validation
Schemas often include "strict" mode and specific property constraints to ensure the AI does not hallucinate parameters.
- Path Validation: Tools like
list_directoryandReadexplicitly state in their descriptions that paths must be absolute. - Conflict Prevention: The
edit_fileschema enforces thatold_strandnew_strmust be different. - Result Limits: Tools like
Grepinclude hardcoded limits in their logic (e.g., 250 matches total, 15 matches per file) to manage token usage.
Sources: Amp/gpt-5.yaml:454, Amp/gpt-5.yaml:610-620, Amp/claude-4-sonnet.yaml:705-715
Conclusion
The Tools JSON Schema Analysis reveals a highly structured environment where agent capabilities are strictly bounded by predefined interfaces. By utilizing standard JSON formats for file operations, terminal commands, and agent delegation, the system ensures consistent and predictable behavior across different LLM backends. These schemas are critical for maintaining system integrity, especially when agents are performing autonomous edits or executing shell commands in a sandbox environment.