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
- Identify the operations needed for the user's job.
- In Veryfront Agent, call
veryfront__tool_searchto progressively loadveryfront__list_agent_tool_referencesfor the current run. - Call
veryfront__list_agent_tool_referenceswith the selectedproject_referenceandsource_target_kind, plus a capability query or exact candidate names. Use the returnednamevalues exactly intool_ids. - Use
veryfront__list_integrationsandveryfront__get_integrationfirst, then attach the exact returned integration tool IDs intool_ids. - Use
veryfront__list_toolsto inspect project-local tools. Followpage_info.nextascursorfor more results. Useveryfront__get_toolto read one definition. - Studio and Cloud platform web tools returned by
veryfront__list_agent_tool_references, such asweb_searchandweb_fetch, belong intool_ids. - Provider-native web tools in Veryfront Code belong in
providerTools. The equivalent MCP field isprovider_tool_ids. - 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.
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:
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
Knowledge Q&A
A project knowledge Q&A agent needs both discovery and content retrieval:
veryfront__search_knowledgefinds matching knowledge file paths and frontmatter metadata. It does not return file bodies.matched_fieldsdescribes metadata fields that matched the query. It can be[]for browse-style results.veryfront__get_filereads 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:
- Call
veryfront__list_integrationswith the service name. - Call
veryfront__get_integrationfor the selected integration. - Attach exact integration tool IDs returned by
veryfront__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 veryfront__create_agent or veryfront__update_agent, check that every selected tool ID came from one of these sources:
veryfront__list_agent_tool_referencesfor valid project-agent tool referencesveryfront__get_integrationfor integration toolsveryfront__list_toolsfor project-local tools
If the tool cannot be verified from a live source, do not attach it.