Choose agent tools

Use this page when you create or update a project agent and need to decide which tools to attach. It applies to Veryfront Agent, human developers, and external coding agents.

Selection flow

Start from the user’s job, not from every available capability.
Call tool_search to progressively load list_agent_tool_references for the current run.
Call list_agent_tool_references with the selected project and a capability query or exact candidate names. Use the returned name values exactly in tool_ids.
Use list_integrations and get_integration first, then attach the exact returned integration tool IDs in tool_ids.
Use list_tools when you need to inspect project-local tool references.
Studio and Cloud platform web tools returned by list_agent_tool_references, such as web_search and web_fetch, belong in tool_ids.
Provider-native web tools in Veryfront Code belong in providerTools; the equivalent MCP field is provider_tool_ids.
Attach only tools the agent needs for the requested job.

tool_search loads executable tool schemas for the next model step. It does not return or validate agent tool_ids.

Runtime discovery

tool_search({
  "query": "list_agent_tool_references"
})

After the API tool is loaded, search the project-scoped authoring catalog:

Agent reference lookup

list_agent_tool_references({
  "project_reference": "<project>",
  "query": "knowledge"
})

The project-scoped response returns schema-free entries with name, description, source, and attach_via. Use exact returned name values in tool_ids, never provider_tool_ids. Use a capability query to discover candidates. Use exact names to validate known candidates before creating or updating an agent. Do not attach knowledge_lookup. It is a legacy internal helper, not a project-agent tool.

Common patterns

Pattern	Typical tool IDs	Guidance
Knowledge Q&A	`search_knowledge`, `get_file`	Use `search_knowledge` to find matching project knowledge files, then call `get_file` on up to 3 relevant returned paths before answering. Say when project knowledge does not support the answer only after reading candidates or retrying with a refined query.
Web research	`web_search`, `web_fetch`	Use search to discover candidate pages, then fetch the relevant page content before summarizing or citing.
File and content work	`list_files`, `get_file`	Start read-only. Add mutation tools only when the agent must create, edit, or delete project files.
Integration assistant	Integration tool IDs returned by `get_integration`	Search integrations by service name, read the integration details, and attach only the returned actions needed for the job.
Human input	`form_input`	`form_input` collects structured human input. It is not a tool-approval gate.
Agent delegation	`invoke_agent`	Attach only when the agent must call another project agent. Prefer direct tools for single-agent tasks.
Sandbox execution	`bash`	Attach only when shell execution is part of the job, such as running deterministic checks or inspecting generated artifacts.

Knowledge Q&A

A project knowledge Q&A agent needs both discovery and content retrieval:

search_knowledge finds matching knowledge file paths and frontmatter metadata. It does not return file bodies.
matched_fields describes metadata fields that matched the query. It can be [] for browse-style results.
get_file reads the matched file body.

In the agent prompt, tell the agent to search knowledge first, read the relevant files with get_file, answer only from supported content, and say when the knowledge base does not contain enough information. When search_knowledge returns candidates, read the most relevant file bodies with get_file before declaring the knowledge base unsupported. Read up to 3 candidates per search, chosen by path, title, description, or matched_fields. If none support the answer, refine the query and retry before saying the knowledge base does not contain enough information. Add these rules to the system prompt: “The platform attaches exact source citations automatically after successful get_file reads of knowledge files. Do not write a manual Sources section or retype source paths. Treat returned source paths as opaque identifiers. If you mention one inline, copy it character-for-character from the latest search_knowledge or get_file result; never shorten, normalize, or reconstruct it.”

Integration agents

For Gmail, Outlook, Slack, Notion, and similar service assistants, use the integration catalog instead of guessing IDs:

Call list_integrations with the service name.
Call get_integration for the selected integration.
Attach exact integration tool IDs returned by get_integration.
Add platform tools only when the job also needs platform capabilities.

Integration tool IDs go in tool_ids. Provider-native tools go in provider_tool_ids.

Before creating the agent

Before calling create_agent or update_agent, check that every selected tool ID came from one of these sources:

list_agent_tool_references for valid project-agent tool references
get_integration for integration tools
list_tools for project-local tools

If the tool cannot be verified from a live source, do not attach it.

Getting Started

Concepts

Guides

Choose agent tools

Selection flow

Common patterns

Knowledge Q&A

Integration agents

Before creating the agent

​Selection flow

​Common patterns

​Knowledge Q&A

​Integration agents

​Before creating the agent

Selection flow

Common patterns

Knowledge Q&A

Integration agents

Before creating the agent