AICOS Tools Reference

This page provides a complete reference for all tools available to AICOS during execution. These tools enable AICOS to manage projects, communicate with stakeholders, track knowledge, and coordinate work.

Tool Categories

Category	Tools	Purpose
Project Management	create_project, update_project, review_project	Manage projects under goals
Task Management	create_project_task, update_project_tasks, complete_project_tasks	Track individual work items (batched)
Goal Management	create_goal, update_goal, review_goal, summarize_active_work	Goal-level planning and review
Knowledge	record_knowledge, retrieve_knowledge, search_outermind_docs	Organizational memory
Communication	respond, send_to, move_conversation, forward_email	Messaging across channels and contacts
Approvals	administer_approvals	Queue management for BO-gated actions
Scheduling	manage_my_settings (setting_area=scheduled_reminders)	Time-based triggers

Project Management Tools

create_project

Creates a new project under an existing goal.

Parameters:

Parameter	Type	Required	Description
goalId	string	Yes	ID of the parent goal
name	string	Yes	Project name
description	string	Yes	Detailed project description
targetDate	date	No	Target completion date
priority	enum	No	high, medium, low (default: medium)

Example:

create_project(
  goalId: "goal-123",
  name: "Competitive Analysis",
  description: "Research and document competitor positioning, pricing, and features for the European market entry strategy.",
  targetDate: "2024-06-30",
  priority: "high"
)

Returns: Project object with assigned ID and initial status.

update_project

Updates an existing project's details or status.

Parameters:

Parameter	Type	Required	Description
projectId	string	Yes	ID of the project to update
name	string	No	Updated project name
description	string	No	Updated description
status	enum	No	active, on_hold, completed, cancelled
progress	number	No	Completion percentage (0-100)
targetDate	date	No	Updated target date

Example:

update_project(
  projectId: "proj-456",
  status: "active",
  progress: 45
)

Returns: Updated project object.

review_project

Single-project deep-read returning project state, tasks, progress metrics, and blockers in one call. (Renamed from project_status_snapshot.)

Task Management Tools

create_project_task

Creates a new task within a project. (Renamed from create_task to disambiguate from non-project tasks.)

Parameters:

Parameter	Type	Required	Description
projectId	string	Yes	ID of the parent project
title	string	Yes	Task title
description	string	No	Detailed task description
assignee	string	No	Person or SME to assign
dueDate	date	No	Task due date
priority	enum	No	high, medium, low
dependencies	array	No	IDs of tasks that must complete first

Example:

create_project_task(
  projectId: "proj-456",
  title: "Gather competitor pricing data",
  description: "Research and document pricing tiers for top 5 competitors in the European market.",
  assignee: "Research SME",
  dueDate: "2024-05-15",
  priority: "high"
)

Returns: Task object with assigned ID.

update_project_tasks

Updates one or more existing tasks in a single call. Always accepts an array — pass a single-element array to update one task. (Replaces the legacy update_task and batch_update_tasks tools.)

Parameters:

Parameter	Type	Required	Description
updates	array	Yes	One or more task-update objects (see fields below)

Each update object:

Field	Type	Required	Description
taskId	string	Yes	ID of the task to update
title	string	No	Updated title
description	string	No	Updated description
status	enum	No	pending, in_progress, blocked, completed
assignee	string	No	Updated assignee
dueDate	date	No	Updated due date
blockedReason	string	No	Reason if status is blocked

Example:

update_project_tasks(
  updates: [
    { taskId: "task-789", status: "in_progress" }
  ]
)

Returns: Array of updated task objects. Each entry goes through the full authorization and safety pipeline.

complete_project_tasks

Marks one or more tasks as completed in a single call. Accepts an array of task IDs.

Parameters:

Parameter	Type	Required	Description
taskIds	array of strings	Yes	IDs of the tasks to complete
outcome	string	No	Summary of what was accomplished
learnings	string	No	Lessons learned (auto-captured as knowledge)

Example:

complete_project_tasks(
  taskIds: ["task-789"],
  outcome: "Compiled pricing data for 5 competitors. Found that our pricing is 15% below market average.",
  learnings: "Competitor B has a hidden enterprise tier not listed publicly; requires sales contact to discover."
)

Returns: Array of completed task objects. If learnings is provided, a knowledge entry is automatically created.

Knowledge Tools

record_knowledge

Stores new organizational knowledge for future reference.

Parameters:

Parameter	Type	Required	Description
content	string	Yes	The knowledge to record
type	enum	Yes	constraint, preference, learning, decision
linkedEntities	array	No	Entities to link (goals, projects, tasks, people)
source	string	No	Where this knowledge came from

Example:

record_knowledge(
  content: "European customers require GDPR compliance documentation before signing contracts. Legal team needs 2 weeks to prepare.",
  type: "constraint",
  linkedEntities: [
    { type: "goal", id: "goal-123" },
    { type: "project", id: "proj-456" }
  ],
  source: "Legal team consultation"
)

Returns: Knowledge entry object with assigned ID.

retrieve_knowledge

Searches organizational knowledge using semantic matching.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Search query describing needed knowledge
type	enum	No	Filter by knowledge type
linkedEntity	object	No	Filter by linked entity
limit	number	No	Maximum results (default: 10, max: 20)

Example:

retrieve_knowledge(
  query: "What do we know about compliance requirements for European expansion?",
  type: "constraint",
  limit: 5
)

Returns: Array of matching knowledge entries ranked by relevance.

Communication Tools

AICOS uses three unified cross-channel communication tools for all outbound messaging. These tools replace the legacy send_message_to_bo, send_email, and reply_chat tools.

respond

Replies to the Business Owner (or whoever is on the other side of the active conversation) on the channel currently open (email, Teams, Slack, or Boardroom). Renamed from send_message to make the in-active-conversation semantic explicit.

Parameters:

Parameter	Type	Required	Description
text	string	Yes	Message content (≤ 8000 chars)
attachments	array	No	File attachments

Returns: Message delivery confirmation.

send_to

Initiates (or appends to) a conversation with any contact on a specified channel. Supports fuzzy contact lookup by name or email.

Parameters:

Parameter	Type	Required	Description
contactId	string	One of	Exact contact ID (contact_{uuid})
contactQuery	string	One of	Fuzzy name or email to search
channel	enum	Yes	email, teams, slack, boardroom, or pa_hub
text	string	Yes	Message content
subject	string	No	Subject line (email only)
attachments	array	No	File attachments
cc	array	No	Additional recipients (email only)

Outbound access controls

The send_to tool respects per-agent Outbound Channel Access settings. By default, agents can only send to contacts classified as internal. See Outbound Messaging Controls for configuration details.

Example:

send_to(
  contactQuery: "Sarah Chen",
  channel: "teams",
  text: "Hi Sarah — can we sync briefly on the EMEA rollout timeline? I have some updated projections from the market analysis."
)

Returns: { conversationId, platformMessageId }.

move_conversation

Moves the active conversation to a different channel (for example, switching from email to Teams). Requires Business Owner approval when the move crosses a trust boundary.

Returns: New conversation binding, or awaiting_bo_confirmation if approval is required.

Approval requests

AICOS no longer exposes a standalone request_approval tool. Approval-style narration to the Business Owner is just a respond (or send_message_to_bo from the system prompt) describing the decision and asking for direction. Tenant-scoped approval queues (escalations, agent-creation proposals, QuickBooks writes, standing approvals) are managed through administer_approvals (see Platform Administration).

Goal Management Tools

update_goal

Updates an existing corporate goal — any field, including progress and status. Replaces the legacy update_goal_progress tool, which has been folded into this unified tool.

Parameters:

Parameter	Type	Required	Description
goalId	string	Yes	ID of the goal to update
name	string	No	Updated goal name
description	string	No	Updated description
completionPercentage	number	No	Overall completion percentage (0-100)
status	enum	No	active, achieved, paused, cancelled
statusReason	string	No	Explanation for status change
milestoneReached	string	No	Description of milestone achieved

Example:

update_goal(
  goalId: "goal-123",
  completionPercentage: 35,
  status: "active",
  milestoneReached: "Completed market research phase with comprehensive competitive analysis"
)

Setting status: "achieved" automatically pins completionPercentage to 100 and records the achievement timestamp.

Returns: Updated goal object. If milestoneReached is provided and status updates are configured for milestones, triggers a status update to the BO.

review_goal

Read-only deep-read of a goal with all its projects and tasks. Use to inspect status before deciding whether to update. (Renamed from review_and_update_goal; the update path now lives on update_goal.)

summarize_active_work

Cross-entity digest read across goals, projects, and tasks — filtered to active/in-progress items only (completed and archived items are excluded). Use at the start of a session to understand current state efficiently. (Renamed from bulk_status_review.)

Scheduling Tools

manage_my_settings (setting_area: "scheduled_reminders")

Schedule, list, cancel, or reschedule reminders. The legacy set_reminder and manage_scheduled_reminders tools fold into the unified manage_my_settings super-tool with setting_area: "scheduled_reminders".

Parameters:

Parameter	Type	Required	Description
setting_area	string	Yes	Always scheduled_reminders for this surface
action	enum	Yes	list, get_details, cancel, reschedule
reminderId	string	For cancel/reschedule	Existing reminder ID
cancelledReason	string	For cancel	Why the reminder is being cancelled
newTriggerDate	datetime	For reschedule	New ISO future datetime

New reminders are scheduled by the underlying execution-loop via internal pipeline calls; LLM-callable scheduling is reserved for future stories.

Example (list pending):

manage_my_settings(
  setting_area: "scheduled_reminders",
  action: "list"
)

Returns: Per-action shape (list of reminders, single reminder details, or confirmation of cancel/reschedule).

Configuring Mailbox Access for AICOS

AICOS can use the search_mailbox tool to search emails across your organization's mailboxes, including the Business Owner's personal mailbox. However, this tool requires explicit access configuration before AICOS can use it.

Why Configuration is Required

The search_mailbox tool uses a fail-closed access model: without configuration, AICOS has no mailbox access. This is a security measure that ensures agents only access mailboxes they are explicitly authorized to search.

When AICOS is first set up, the search_mailbox tool is assigned but its access configuration is not set automatically. You must configure it manually.

How to Configure

1. Navigate to Build > AI Chief of Staff > Tools
2. Find the search_mailbox tool in the list
3. Click the gear icon next to the tool to open the configuration modal
4. Choose an access mode:
   • Full Access - AICOS can search any mailbox in your organization
   • Scoped Access - Restrict to specific mailboxes, departments, or Entra ID groups
5. For Scoped Access, we recommend adding at minimum:
   • The AICOS monitored mailbox (e.g., aicos@company.com)
   • The Business Owner's personal mailbox (e.g., ceo@company.com)
6. Click Save

Recommended Configuration

For most organizations, Scoped Access with the following mailboxes is recommended:

• AICOS monitored mailbox - So AICOS can search its own incoming mail history
• Business Owner's mailbox - So AICOS can research context from the BO's correspondence
• Key department mailboxes - Any shared mailboxes relevant to AICOS's goals (e.g., sales@company.com, support@company.com)

Alternatively, if AICOS needs broad organizational visibility, select Full Access.

Troubleshooting

If AICOS reports that it cannot access a mailbox or you see "Access denied" errors in execution logs:

1. Verify that search_mailbox is assigned and enabled on the AICOS Tools page
2. Check that the mailbox access configuration includes the target mailbox
3. Ensure your Microsoft 365 integration has Mail.Read permissions
4. If your organization uses an Application Access Policy in Exchange Online, verify the target mailbox is included in the allowed security group

For detailed information about access scoping modes (departments, groups, specific mailboxes), see Search Mailbox Tool.

Tool Usage Guidelines

Best Practices

1. Link Entities - Always link knowledge and communications to relevant goals, projects, or tasks for better organization

2. Provide Context - When requesting approvals or sending messages, include sufficient background for the BO to make informed decisions

3. Capture Learnings - Use complete_project_tasks with learnings or record_knowledge to capture insights that benefit future work

4. Set Appropriate Urgency - Reserve urgent for time-sensitive matters; overuse reduces effectiveness

5. Track Progress - Regularly update task and project progress to maintain accurate status visibility

Common Patterns

Creating a Complete Project Structure:

1. create_project() - Create project under goal
2. create_project_task() - Add initial tasks (one call per task)
3. update_goal() - Reflect new project in goal completion percentage

Handling a Blocker:

1. update_project_tasks(updates: [{ taskId, status: "blocked", blockedReason: "..." }])
2. record_knowledge(type: "learning", content: "Blocker description...")
3. respond(text: "Blocked on X — need your input before I can proceed.")

Completing Work:

1. complete_project_tasks(taskIds: [...], outcome: "...", learnings: "...")
2. update_project(progress: new_percentage)
3. update_goal(completionPercentage: new_percentage)

Error Handling

If a tool call fails, AICOS will:

1. Log the error with context
2. Retry with exponential backoff (up to 3 attempts)
3. If still failing, mark the related task as blocked
4. Continue with other work items
5. Report the issue in the next status update

Related Topics

• AICOS Overview - Introduction to AICOS
• Execution Cycle - When and how tools are used
• Knowledge Management - Details on knowledge tools
• Setup Wizard - Initial configuration
• Settings & Customization - Post-setup configuration