THE TOOL REGISTRY

EXAMPLES Example 1: A registry entry. The entry for read_file holds its name, the description "Reads the contents of a file given its path," its permission level of read, and a reference to read_file_handler. When the model asks for read_file, the harness finds this entry, validates the path field, checks that the agent has read permission, and calls the handler. Example 2: Typed handlers. read_file, write_file, and list_directory all inherit from a file handler base that normalizes the path, confirms it stays inside the project folder, and refuses symbolic links that point outside it. One day an engineer discovers that paths containing a certain character sequence slip past the check. She fixes it once in the base, and all three tools are protected immediately. Example 3: On-demand discovery. An agent is connected, through Model Context Protocol servers, to a dozen services that offer 200 tools in total. The user's task is "Schedule a meeting with the design team next Tuesday." A discovery step looks at the task and loads five tools: find_free_time, create_calendar_event, list_team_members, send_invite, and get_timezone. The other 195 tool definitions never enter the context for this turn, saving tens of thousands of tokens and reducing the chance of choosing a wrong tool. Example 4: Versioning and deprecation. A bug in send_email_v1 causes it to drop attachments over a certain size. The team writes send_email_v2, which fixes the bug and adds a new optional field. The registry marks v1 as deprecated, adds a warning to its output ("send_email_v1 will be removed on April 1; please use send_email_v2"), and keeps it running for six months so existing automations do not suddenly break. A log report shows two internal workflows still call v1, so the team contacts the owners to migrate.