Choose agent tools

Execution reference: This page specifies the tool protocol for automation agents. For instructions to follow in Studio, use the user guide.

Choose tools for the agent's job using the live project and integration catalogs. This contract applies to Veryfront Agent, developers and external coding agents.

Selection flow

  1. Identify the operations needed for the user's job.
  2. In Veryfront Agent, call veryfront__tool_search to progressively load veryfront__list_agent_tool_references for the current run.
  3. Call veryfront__list_agent_tool_references with the selected project_reference and source_target_kind, plus a capability query or exact candidate names. Use the returned name values exactly in tool_ids.
  4. Use veryfront__list_integrations and veryfront__get_integration first, then attach the exact returned integration tool IDs in tool_ids.
  5. Use veryfront__list_tools to inspect project-local tools. Follow page_info.next as cursor for more results. Use veryfront__get_tool to read one definition.
  6. Studio and Cloud platform web tools returned by veryfront__list_agent_tool_references, such as web_search and web_fetch, belong in tool_ids.
  7. Provider-native web tools in Veryfront Code belong in providerTools. The equivalent MCP field is provider_tool_ids.
  8. Attach only tools the agent needs for the requested job.

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

js
veryfront__tool_search({
  "query": "veryfront__list_agent_tool_references"
})

After the API tool is loaded, search the authoring catalog for the active project and source target. This example uses project source. For a preview branch, use source_target_kind: "preview_branch" and the matching target_branch_id required by the live schema:

js
veryfront__list_agent_tool_references({
  "project_reference": "<project>",
  "source_target_kind": "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

PatternTypical tool IDsGuidance
Knowledge Q&Averyfront__search_knowledge, veryfront__get_fileUse veryfront__search_knowledge to find matching project knowledge files, then call veryfront__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 researchweb_search, web_fetchFor project agents whose runtime exposes these tools, search for candidate pages and fetch the content before citing it. Veryfront Agent itself currently has no external web search or fetch.
File and content workveryfront__list_files, veryfront__get_fileStart read-only. Add mutation tools only when the agent must create, edit, or delete project files.
Integration assistantIntegration tool IDs returned by veryfront__get_integrationSearch integrations by service name, read the integration details, and attach only the returned actions needed for the job.
Human inputveryfront__form_inputveryfront__form_input collects structured human input. It is not a tool-approval gate.
Agent delegationveryfront__invoke_agentAttach only when the agent must call another project agent. Prefer direct tools for single-agent tasks.
Sandbox executionbashAttach 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:

  • veryfront__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.
  • veryfront__get_file reads the matched file body.

In the agent prompt, require a knowledge search followed by reads of up to 3 relevant file bodies. Choose candidates by path, title, description or matched_fields. Answer only from supported content. If the candidates do not support an answer, refine the query and retry before reporting that knowledge is insufficient.

Add these rules to the system prompt: "The platform attaches exact source citations automatically after successful veryfront__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 veryfront__search_knowledge or veryfront__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:

  1. Call veryfront__list_integrations with the service name.
  2. Call veryfront__get_integration for the selected integration.
  3. Attach exact integration tool IDs returned by veryfront__get_integration.
  4. 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 veryfront__create_agent or veryfront__update_agent, check that every selected tool ID came from one of these sources:

  • veryfront__list_agent_tool_references for valid project-agent tool references
  • veryfront__get_integration for integration tools
  • veryfront__list_tools for project-local tools

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