Built-in Tools

As well as the functions you assign, FYAI provides some tools to agents itself. You don't write any code for them. Some are attached automatically. Others you assign like any other function: they appear in your Functions library with the type Platform built-in and are read-only.

At a glance

Tool name	What it does	How an agent gets it
remember	Saves one fact to the agent's long-term memory	Automatically, when the agent's Memory checkbox is ticked
recall	Searches the agent's long-term memory	Automatically, when Memory is ticked
read_tool_result	Reads lines from a large tool result that was saved instead of returned in full	Automatically, for agents with at least one tool
search_tool_result	Regex search inside a saved tool result	Automatically, for agents with at least one tool
query_tool_result	Navigates a saved JSON tool result by path	Automatically, for agents with at least one tool
search_conversation_history	Searches earlier messages in the current chat	Assign it as a function
wait_for_event	Waits for a platform event instead of sleeping and polling	Assign it as a function
hand_off_to_agent	Hands a one-to-one chat over to a specialist agent	Assign it as a function, and grant the target on the Sub-agents tab

Sub-agent calls (invoke_sub_agent) work similarly and are covered below.

Turning built-in tools on and off

Organisation Owners and Admins can turn each built-in tool on or off for the whole organisation in Settings → Built-in Tools. The section isn't shown to anyone else.

• Each row shows the tool's name, the description the model sees, and an Enable switch.
• Tools that are added to agents without you assigning them carry an Automatic chip.
• Turning a tool off removes it from every agent in the organisation, including agents that have it assigned.
• Every built-in tool is on by default.

note

If you turn off the result readers, oversized tool results are still saved instead of being returned in full, but agents can no longer open them. Leave the readers on unless you have a reason not to.

Memory tools: remember and recall

When you tick Memory on an agent, it gets two tools. Its system message also tells it they exist, and it receives a Memory Context block of relevant memories at the start of each chat.

• remember saves one self-contained fact, such as a preference, a decision or a detail about the user's environment.
  • Limit: 4,000 characters per fact.
  • If saving fails, the agent is told so and carries on.
• recall searches the agent's memories across all tiers.
  • Returns up to 10 matches, each labelled with its tier and age.
  • The agent is told to treat recalled memories as data, not instructions.

Both tools only ever read and write the calling agent's own memory, for the current organisation, project and user. They never ask for approval.

See Memory for retention, tiers and the Memory Policy setting.

Large tool results: saving and the result readers

Some tool results are too big to put into the model's context, such as a large API response or a long file. FYAI saves these to the session workspace and gives the model a short pointer instead. The pointer says:

• how big the result was;
• a reference ID;
• a hint about its JSON structure, if it has one;
• which reader to use;
• the first 600 characters.

The model then uses the readers to look at just the part it needs:

Tool	Parameters	Limits
read_tool_result	ref, offset (start line, default 0), limit (lines, default 200)	Up to 2,000 lines per call
search_tool_result	ref, pattern (Python regular expression), max_matches (default 50)	Up to 500 matches. Each match includes 120 characters of context on either side and an offset to pass to read_tool_result
query_tool_result	ref, path (for example ., [0:20] or .results[0].name), max_chars (default 4,000)	200 to 20,000 characters

When results are saved

• A result is saved when it's longer than the team's Tool Summary Max Characters setting. Leave it empty to use the platform default of 2,000 characters.
• One-to-one chats have no team, so they always use the default.
• Images and binary results are never saved this way.

What people see

• People in the chat still see the full result. Only the model's copy is shortened.
• Saved results last only for the current run. If the agent tries to use a reference from an earlier turn, it's told to call the tool again.

Exempting a function

• To always return a particular function's full result, set its spill_exempt field. This is API-only.

search_conversation_history

Searches the messages in the current chat session. Agents use it to recall earlier decisions in a long conversation.

Parameter	Default	Description
query	required	The text to look for
role	none	Only search messages from user, assistant or system
limit	20	Maximum results

It only works inside a chat session, and it never asks for approval.

wait_for_event

Lets an agent wait for something outside the chat instead of sleeping and polling. Examples include a CI check finishing, a webhook arriving, or a long external job completing.

Parameter	Default	Description
kind	required	The event type to wait for, matched as a prefix, for example github.check_suite
match	none	Payload fields that must match exactly, for example {"pr": 420}
timeout_seconds	900	How long to wait. The maximum is 3,300 seconds (55 minutes)

It returns as soon as a matching event arrives in your organisation and project. Otherwise it reports a timeout and tells the agent to check the status directly. It never asks for approval. The run stays active while it waits.

For where events come from, see Event Sources and Webhooks.

hand_off_to_agent

Hands the current conversation to a specialist agent. The specialist continues with the user in a new session that includes the full history, and the chat switches over to it.

Parameter	Description
agent_name	The specialist's exact name
message	The user's request, in their own words

Conditions

• It works only in one-to-one chats with an agent, not inside teams.
• The target must be in the same project, must be active, and must not be the calling agent.
• The target must be granted on the calling agent's Sub-agents tab.
• A conversation can be handed off only once.

Calling sub-agents

An orchestrating agent can run another agent as a tool and use its answer. This is set up as a function rather than a registry built-in. Assign the invoke_sub_agent function to the orchestrator; the model then calls it with:

Parameter	Description
agent_name	The exact name of the agent to run
task_input	The task or instructions for the sub-agent
prior_messages	Optional. Messages returned by an earlier call to the same sub-agent, so it remembers earlier turns
llm_config_override_id	Optional. Run the sub-agent on a different model for this call
resume_execution_id	Optional. Keep waiting on a run that is still going (see below)

Rules

• Permission. The orchestrator may only call agents granted on its Sub-agents tab. Otherwise the call fails with a message telling you to grant it there.
• Depth. Chains can be at most 5 agents deep, and an agent already in the chain can't be called again.
• Long runs. Each call waits up to 4 minutes. If the sub-agent is still working, the call returns "status": "running" with an execution ID. The orchestrator calls again with resume_execution_id to keep waiting, rather than starting a new run.
• Sessions. Each sub-agent run gets its own linked chat session, and appears in the parent chat as a delegation.
• Missions. When the call is part of a mission, the sub-agent appears as its own node on the mission canvas.

Related

• Agents
• Functions
• Memory
• Team Settings, including Tool Summary Max Characters