Agent Tools

Tools are the actions an agent can take during a turn - reading files, querying the model, building a project, asking the user a question, and so on. An agent only sees the tools listed in its tools: frontmatter, plus the always-available use_skill tool.

This document lists every built-in tool, what it does, and where it makes sense to use it.

Quick lookup by purpose

Want to… Use
Find files by name pattern glob
Search file contents (regex) grep, search_files
List a folder's contents list_directory
Get a high-level project overview get_project_overview
Read a source file read_file
Write a whole file write_file
Patch a block inside a file patch_file
Delete a file delete_code_file
Apply staged changes to disk apply_staged_file_changes
Build a .NET project dotnet_build
Run .NET tests dotnet_test
Run a configured task run_task
Read the Intent designer model get_designer_model_snapshot
Read details for a model element get_designer_element_details
Read a designer diagram get_designer_diagram_snapshot
Search the model with regex find_designer_elements
Modify the designer model apply_change_model_operations
Modify a diagram's layout apply_change_diagram_layout
Run an existing designer action execute_designer_element_action
List a designer's package references get_designer_package_references
Run the Software Factory and stage changes run_software_factory
Hand off work to a coding-agent task tab create_ai_task
Dispatch a sub-agent for a focused task create_sub_agent
Start parallel child chats (with approval) start_child_chats
List this chat's child chats list_child_chats
Message one of this chat's child chats message_child_chat
Stop a child chat's current turn stop_child_chat
Run an ad-hoc shell command shell
Read a pull request's open review threads get_pull_request_review_threads
Search Intent / org documentation search_docs
Ask the user a question (multi-choice) ask_user_question
Track progress with a todo list todo_update
Iterate on a written plan write_plan
Request approval to implement a plan implement_plan
Load a skill on demand use_skill

Notes on context

Tools aren't tied to a specific context - coding and modeling agents can pick from the same toolbox. In practice, certain tools only make sense in certain contexts:

  • Designer tools (get_designer_*, find_designer_elements, apply_change_*, execute_designer_element_action, run_software_factory) work against the Intent model, so they belong in modeling agents.
  • File-mutation tools (write_file, patch_file, delete_code_file, apply_staged_file_changes, dotnet_build, dotnet_test, run_task) operate on the application's output codebase, so they belong in coding agents.
  • File-search tools (grep, glob, read_file, list_directory, get_project_overview, search_files) operate on the application's output codebase and work in both contexts.
  • Conversation tools (ask_user_question, todo_update, use_skill) work in any context.
  • Plan-mode tools (write_plan, implement_plan) are only meaningful for planning agents.

A tool's "context" is determined by which agents you list it in - there's no automatic enforcement.

Most tools require an applicationId parameter to identify which application's output folder or designer model to act on. Most also require a short intention string explaining why the tool is being called - this is shown to the user as a one-line summary of the action.

Tool behaviour worth knowing

  • patch_file accepts literal search/replace blocks only. Unified-diff-style patches are not supported.
  • apply_staged_file_changes requires the explicit list of files to apply, rather than applying everything currently pending.
  • shell runs ad-hoc bash or PowerShell commands, with output streamed to a terminal and persisted. A running command can be backgrounded or killed.
  • create_sub_agent dispatches a sub-agent - Coding, Discovery or Spec Worker - for an isolated piece of work. Multiple dispatches can run concurrently.
  • start_child_chats proposes 1 to 8 new chats, each in its own worktree by default, on a card the person approves. They run as full chats nested under this one, and this chat is sent each one's last reply when it finishes, fails, is stopped by the person or needs them. list_child_chats, message_child_chat and stop_child_chat act on this chat's own child chats only, and sub-agents can't use any of the four. See Split a big task across child chats.
  • Agents are blocked from writing to Intent Architect's protected files (.intent, Intent.Metadata, .application.config).

Adding tools to an agent

Tools are wired up in an agent definition's frontmatter. Only listed tools are available - and use_skill is always added on top:

---
name: My Reviewer
context: modeling
tools:
  - search_docs
  - get_designer_model_snapshot
  - find_designer_elements
  - read_file
  - grep
  - ask_user_question
maxIterations: 8
---

You are a model reviewer…

If a tool name doesn't match a known tool, it's silently skipped at startup.