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	projects.create, projects.update, projects.get	Manage projects under goals
Task Management	project_tasks.create, project_tasks.update	Track individual work items (batched)
Goal Management	goals.create, goals.update, goals.get, active_work.get	Goal-level planning and review
Knowledge	agent_memory.create, agent_memory.search, product_docs.search	Organizational memory
Communication	messages.reply, messages.send:person, messages.move, mailbox_messages.forward:me	Messaging across channels and contacts
Approvals	approvals, standing_approvals	Queue management for BO-gated actions
Scheduling	scheduled_actions	Time-based triggers

Project Management Tools

projects.create

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:

projects.create(
  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.

projects.update

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:

projects.update(
  projectId: "proj-456",
  status: "active",
  progress: 45
)

Returns: Updated project object.

projects.get

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

Task Management Tools

project_tasks.create

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:

project_tasks.create(
  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.

project_tasks.update (batch updates)

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:

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

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

project_tasks.update (completing 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:

project_tasks.update(
  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

agent_memory.create

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:

agent_memory.create(
  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.

agent_memory.search

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:

agent_memory.search(
  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 supervisor-message, direct email-send and chat-reply tools.

messages.reply

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.

messages.send:person

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 messages.send:person action 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:

messages.send:person(
  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 }.

messages.move

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 messages.reply (or messages.send:supervisor 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 the approvals and standing_approvals tools (see Platform Administration).

Goal Management Tools

goals.update

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:

goals.update(
  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.

goals.get

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 goals.update.)

active_work.get

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

scheduled_actions

Schedule, list, cancel, or reschedule reminders, follow-ups, and scheduled project runs. The legacy reminder-scheduling tools fold into the unified scheduled_actions tool.

Parameters:

Parameter	Type	Required	Description
action	enum	Yes	list, get, create, update
id	string	For get/update	Existing scheduled action ID
type	enum	For create	reminder, follow_up, project_run
status	enum	For update	Set to cancelled to cancel
dueAt	datetime	For create/update	Trigger date/time (ISO); set on update to reschedule

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

Example (list pending):

scheduled_actions(
  action: "list"
)

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

Configuring Mailbox Access for AICOS

AICOS can use the other-mailbox search tool (mailbox_messages.search:other) 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 other-mailbox search 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 other-mailbox search tool is assigned but its access configuration is not set automatically. You must configure it manually.

How to Configure

1. Navigate to Boardroom > Settings > Tools
2. Find the other-mailbox search tool (mailbox_messages.search:other) 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 the other-mailbox search tool (mailbox_messages.search:other) is assigned and enabled in the Tools section of Boardroom > Settings
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 project_tasks.update with learnings or agent_memory.create 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. projects.create() - Create project under goal
2. project_tasks.create() - Add initial tasks (one call per task)
3. goals.update() - Reflect new project in goal completion percentage

Handling a Blocker:

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

Completing Work:

1. project_tasks.update(taskIds: [...], outcome: "...", learnings: "...")
2. projects.update(progress: new_percentage)
3. goals.update(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