Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@kairos Create a task in the Development plan: "Review Q3 budget draft.""
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Microsoft Planner MCP server that writes tasks.
An agent creates tasks and buckets in your Planner plans, lists what is there,
and marks tasks complete. Sign-in is delegated device-code against your own
Entra app with the single Graph scope Tasks.ReadWrite; the token reaches only
the plans you are a member of and nothing else in the tenant.
kairos is the sibling of iris, the mail server that cannot send. They are deliberately separate. iris's value is an absent capability; a Planner writer's value is the write itself. Creating a task creates a task. Completing one completes one. kairos does not pretend otherwise, so read what it can do before you install it.
uvx kairos-mcp # run without installing
pip install kairos-mcpPython 3.10 or newer. macOS ships Python 3.9, which is too old — mcp
requires 3.10+. Use uv (it comes with uvx and
manages its own Python), or install a current Python with Homebrew
(brew install python@3.12). The system python3 on macOS will not work.
Related MCP server: Microsoft Graph MCP Server
You must register your own Entra application. There is no shared app registration and no hosted service — kairos talks directly from your machine to your tenant. A shared app would mean trusting someone else's client ID with write access to your plans.
Entra admin centre → App registrations → New registration. Single tenant is fine. No redirect URI needed.
Authentication → Settings → enable Allow public client flows. Device code sign-in needs this. No client secret is used anywhere.
API permissions → Microsoft Graph → Delegated → add
Tasks.ReadWrite ("Create, read, update and delete user's tasks and
projects"). Nothing else.
Copy the Application (client) ID and Directory (tenant) ID. Neither is a secret.
Then add kairos to your MCP client:
{
"mcpServers": {
"kairos": {
"command": "uvx",
"args": ["kairos-mcp"],
"env": {
"KAIROS_CLIENT_ID": "<application (client) id>",
"KAIROS_TENANT_ID": "<directory (tenant) id>",
"KAIROS_DEFAULT_PLAN": "Development"
}
}
}
}Sign in once, either from a terminal:
KAIROS_CLIENT_ID=... KAIROS_TENANT_ID=... uvx kairos-mcp author from inside the MCP client: call kairos_login, open the URL, enter the
code, then call kairos_login_finish. Either way the token cache lands in
~/.config/kairos/token_cache.json, mode 600, and refreshes silently from then
on.
KAIROS_DEFAULT_PLAN is optional. Without it, every call must name a plan —
unless your account can see exactly one, in which case that one is used.
kairos is a local stdio MCP server: your MCP client launches it as a child process on the same machine. It works with any client that supports local stdio servers — Claude Desktop, Cursor, the Grok CLI and others. It does not work with clients that only accept remote MCP connectors over HTTP.
Tool | What it does |
| Starts device-code sign-in, returns a URL and a code |
| Completes sign-in; safe to call repeatedly while you type the code |
| Who is signed in, whether Graph is reachable, how many plans are visible |
| Every plan you can see, with its buckets and IDs (cached a few minutes; |
| Creates a task: |
| Creates a bucket in a plan. Idempotent — an existing bucket of that name is returned, not duplicated |
| Tasks in a plan (or |
| Marks a task 100% by |
Plans and buckets are matched by name, case-insensitively, or by ID. A partial
name works when it is unambiguous. Omit bucket and the plan's first bucket is
used.
complete_planner_task(title="deploy") searches open tasks in the plan. One
match: it completes it. Two or more: it stops and lists them with IDs so you can
re-call with the exact task_id. It never picks one for you.
kairos-mcp run the MCP server on stdio (what your client launches)
kairos-mcp auth interactive device-code sign-in
kairos-mcp status who is signed in, is Graph reachable
kairos-mcp logout remove the token cacheA refresh token stops working after a password change, an admin revocation, or
long disuse. Every tool then returns a message that says so and how to fix it:
kairos-mcp auth in a terminal, or kairos_login → kairos_login_finish from
the client. Nothing else needs to change.
Can: create tasks and buckets in any plan you are a member of; set a task's notes and due date at creation; list plans, buckets and tasks; mark a task complete or reopen it.
Cannot: delete anything — there is no delete tool, and the design keeps it that way. Assign people. Set priority, labels, checklists or attachments. Edit an existing task's title, notes or due date. See plans you are not a member of.
Tasks.ReadWrite is the narrowest Graph scope that permits creating a Planner
task. It also permits reading and updating every task in every plan you belong
to, and in principle deleting them. kairos does not expose delete, but the
token could — the boundary is this code, not Microsoft's consent screen. If
that distinction matters to you, it should; see SECURITY.md.
Kill switch — create ~/.config/kairos/DISABLED, or set
KAIROS_DISABLED=1, and every tool refuses.
Audit log — every write (login, create, complete, reopen) is appended to
~/.config/kairos/audit.log.
KAIROS_CONFIG_DIR moves the cache, log and kill-switch file elsewhere;
KAIROS_TOKEN_CACHE and KAIROS_AUDIT_LOG override individual paths.
A task's notes are not on the task; they live on a child details entity that
Graph guards with an ETag. kairos creates the task, reads the details ETag, then
PATCHes with If-Match. Completion is the same dance on the task itself.
Planner throttles hard, so every call retries on 429 with Retry-After and
there is a short pause between chained calls. New tasks and buckets are pinned
to the top of their column (orderHint: " !").
MIT — see LICENSE.
Mark a Planner task complete (or reopen it). This is a real write.
Give either task_id (exact, preferred) or title. A title is matched against OPEN tasks only (COMPLETED tasks when reopen=true); if it matches more than one, this refuses and lists the candidates rather than guessing.
Args: task_id: Exact Planner task ID. Preferred when known. title: Task title or a distinctive part of it. Used only if task_id is empty. plan: Plan to search when matching by title. Empty uses the default plan. reopen: Set true to undo a completion (sets 0%) instead.
| Name | Required | Description | Default |
|---|---|---|---|
| plan | No | ||
| title | No | ||
| reopen | No | ||
| task_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral disclosure. It openly states this is a real write, warns that ambiguous title matches cause a refusal with candidate listing rather than a guess, and clarifies that reopen sets 0%. These are non-obvious behaviors that significantly aid the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized: a two-sentence summary front-loads the core action and warning, followed by a clean 'Args:' list with bullet-style explanations. Every sentence carries information; there is no fluff or repetition. The structure makes scanning quick and effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description appropriately omits return-value details. It covers the tool's purpose, parameter usage, ambiguity handling, and the reopen effect. For a write operation with a clearly defined parameter contract, nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, and it does thoroughly. Each parameter is explained: task_id is 'Exact Planner task ID. Preferred when known.'; title is 'Task title or a distinctive part of it' and is used only when task_id is empty; plan specifies the search scope; reopen is defined as 'undo a completion (sets 0%)'. This adds meaning well beyond the bare schema types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Mark a Planner task complete') plus an explicit alternative ('or reopen it'), and clearly distinguishes itself from sibling tools like create_planner_task and list_planner_tasks. The phrase 'This is a real write' reinforces its mutating nature, leaving no ambiguity about the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on parameter selection: 'Give either task_id (exact, preferred) or title' and explains the fallback logic when using title (matching open tasks only, and reopen behavior). It also explains when to set reopen to undo a completion. This tells the agent exactly how and when to invoke the tool, including the preferred path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a bucket (board column) in a Planner plan. Idempotent: if a bucket with that name already exists (case-insensitive) its ID is returned and nothing is created.
Args: bucket_name: Name of the bucket. plan: Plan name or ID. Empty uses KAIROS_DEFAULT_PLAN / the only plan.
| Name | Required | Description | Default |
|---|---|---|---|
| plan | No | ||
| bucket_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It explicitly discloses idempotency, case-insensitive matching, that nothing is created on duplicates, and that the existing bucket's ID is returned. It does not cover authentication or error scenarios, but the main side-effect behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: one sentence for purpose, one for critical idempotency behavior, then a minimal Args list. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter create tool with an output schema, the description covers purpose, idempotent duplicate handling, and plan resolution. It could add an explicit login prerequisite, but auth is handled through sibling auth tools and the core behavior is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the Args section must compensate. It explains bucket_name as the name and, more valuably, decodes plan as a name or ID with empty falling back to KAIROS_DEFAULT_PLAN or the only plan — meaning beyond the schema's bare titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence gives a specific verb and resource: 'Create a bucket (board column) in a Planner plan.' This clearly distinguishes it from siblings like create_planner_task and list_planner_plans by naming the object being created and its container.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied by the create action, and the idempotency note explains that calling it again returns an existing bucket's ID rather than failing. However, it never names alternatives or says when not to use it, leaving tool-selection guidance implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a task in Microsoft Planner. This is a real write: the task exists the moment this returns.
Args: title: Short, action-oriented task title (required). notes: Longer context for the task body (Planner "Notes"). plan: Plan name (case-insensitive) or ID. Empty uses KAIROS_DEFAULT_PLAN, or the only plan if the account has exactly one. bucket: Bucket within the plan, by name or ID. Empty uses the plan's first bucket. Call list_planner_plans to see what exists. due_on: Due date as YYYY-MM-DD, or empty for none.
| Name | Required | Description | Default |
|---|---|---|---|
| plan | No | ||
| notes | No | ||
| title | Yes | ||
| bucket | No | ||
| due_on | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It explicitly discloses that this is a persistent write with immediate effect, explains default plan/bucket resolution, and specifies the due_on format. It doesn't cover permission requirements or failure behavior, but the core side effect is transparent and well communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is file:///home/username/Projects/sd-gen-benchmark/tmp_files/http:--aiclash.com-.htmlcompact and front-loaded: one sentence states purpose and side effect, followed by a tight bullet list of arguments. There is no filler, and each line adds concrete guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
All five parameters are covered with defaults and formats, the write side effect is disclosed, and the description references list_planner_plans for discovery. Since an output schema is present, return details are not needed. Minor gaps remain around invalid plan/bucket behavior and auth prerequisites, but the overall picture is solid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates by explaining every parameter: title's required, action-oriented nature; notes as task body; plan and bucket as name-or-ID with default resolution; and due_on date format. Each parameter gains meaning well beyond the bare schema definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a task in Microsoft Planner' with a specific verb and resource. The phrase 'This is a real write: the task exists the moment this returns' also helps distinguish it from read-only or list-like sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool—creating a Planner task—and even points to list_planner_plans for discovering existing plans. It doesn't explicitly contrast with create_planner_bucket or complete_planner_task, but the task-creation use case is well delineated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report whether kairos is signed in, as whom, whether Graph is reachable, and how many plans are visible.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It honestly describes what the tool reports, but it does not disclose whether the call is strictly read-only, whether it makes network requests beyond Graph reachability, or how it behaves on failure. The listed outputs give reasonable transparency, but not full behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One tightly packed sentence covers all four report dimensions with no filler. The most important outcome ('whether kairos is signed in') is front-loaded, and the rest follows in a logically ordered list.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless status tool with an output schema, the description is sufficiently complete. It names every meaningful category an agent needs to interpret the result, and the output schema can handle exact return formatting.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100%, so parameter semantics are effectively vacuous. The baseline for a no-parameter tool is 4; the description adds nothing about parameters because none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Report') and names the exact resource and outcome dimensions: sign-in state, identity, Graph reachability, and visible plan count. This clearly separates it from login flow and planner task tools, so an agent knows what this tool does without inspecting schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit statement about when to use this tool versus alternatives like kairos_login or list_planner_plans. The behavior implies it is a preflight status check, but the description never states that it should be called before login or before planner operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a device-code sign-in to Microsoft 365. Returns a URL and a code for the human to enter in a browser; then call kairos_login_finish() to complete. Only needed once, or after the refresh token lapses (for example after a password change).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the flow: returns a URL and code, requires human browser entry, and completes via a follow-up call. It also explains when it is needed (once or after token lapses). While it does not explicitly state whether it invalidates existing tokens or requires prior auth, for a login initiation this level of disclosure is generally adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short, purposeful sentences with no fluff. It front-loads the primary action, then describes the output and next step, and finally the usage condition. Every sentence earns its place, making it both concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the action, output (URL and code), the required human step, the follow-up call, and the circumstances for use. It does not mention error handling or the role of kairos_auth_status, but given the presence of an output schema and the simplicity of the tool, this is largely sufficient. A minor gap is the lack of explicit mention of any prerequisites or side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no need for the description to explain parameter semantics. The baseline for 0 parameters is 4, and the description appropriately focuses on the action and flow rather than parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Start a device-code sign-in to Microsoft 365' and specifies it returns a URL and a code. It explicitly distinguishes the tool from its sibling kairos_login_finish by instructing to call that to complete the flow, leaving no ambiguity about its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use the tool: 'Only needed once, or after the refresh token lapses (for example after a password change).' It also directs the agent to call kairos_login_finish() next, framing the complete workflow. This is sufficient for an agent to decide between this and related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Complete a device-code sign-in started with kairos_login(). Call after entering the code in the browser. Waits up to ~60s; if the code has not been entered yet, it says so and can simply be called again.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses that the tool waits up to ~60 seconds, reports if the code has not been entered, and supports repeated invocation. This is meaningful transparency for a blocking zero-parameter action, though failure modes and exact return behavior remain unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences: the first identifies the purpose and prerequisite, the second covers timeout and retry behavior. There is no filler or repetition, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description covers the core scenario, the prerequisite, the blocking behavior, and the retry strategy. Nothing essential appears to be missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing for the description to explain about inputs. Per the rubric, a zero-parameter tool gets a baseline of 4, and the description appropriately focuses on behavior rather than parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Complete a device-code sign-in') tied to a named precondition (kairos_login()). It clearly distinguishes itself from kairos_login, the starting step, and kairos_auth_status, the status-check sibling. An agent can immediately understand what this tool is for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit timing guidance: call after entering the code in the browser, and feel free to call again if the code has not been entered yet. This tells the agent when to use the tool and how to retry, though it does not explicitly contrast with kairos_auth_status or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the Planner plans this account can see, each with its buckets and IDs. Results are cached for a few minutes; pass refresh=true to force a re-read (for example after someone added a bucket in the Planner UI).
| Name | Required | Description | Default |
|---|---|---|---|
| refresh | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden)Skip. It discloses caching behavior, the refresh flag's effect, and the account-scoped visibility. It doesn't mention auth requirements or potential side effects, but for a list operation with one parameter, the disclosed caching semantics add meaningful transparency beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The primary purpose is front-loaded, and the caching/refresh detail is placed second, making the most important information immediately accessible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple operation, one parameter, and an existing output schema, the description covers purpose, scope, and the refresh parameter. It doesn't mention login requirements or error conditions, but those are likely implied by the sibling auth tools and don't impede correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a boolean with a default, but the description fully explains the parameter's semantics: 'pass refresh=true to force a re-read' with a concrete example. This is exactly the kind of meaning the schema alone cannot convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('Planner plans'), explicitly scopes to plans 'this account can see', and notes that it returns buckets and IDs. This clearly differentiates it from sibling tools like list_planner_tasks and create_planner_bucket.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concrete usage trigger for the refresh parameter ('after someone added a bucket in the Planner UI') but does not explicitly state when to choose this tool over alternatives such as list_planner_tasks. The implied context is clear, but no exclusions or alternative routing are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Planner tasks with their IDs, so a task can be referenced or completed.
Args: plan: Plan name or ID. Empty uses KAIROS_DEFAULT_PLAN / the only plan. Pass "" to list every plan the account can see. bucket: Optional bucket name to filter by (ignored with plan=""). include_completed: Include tasks already at 100%. Defaults to open only.
| Name | Required | Description | Default |
|---|---|---|---|
| plan | No | ||
| bucket | No | ||
| include_completed | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With zero annotations, the description carries the full behavioral burden and does meaningful work: it discloses the empty-plan default (KAIROS_DEFAULT_PLAN / the only plan), the '*' wildcard behavior, the interaction that bucket is ignored when plan='*', and the include_completed default of open-only. It does not cover auth requirements or pagination, but for a read-style list tool the disclosed defaults and edge cases are substantial and non-obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded purpose sentence followed by a tight Args block with zero filler. Every parameter line earns its place with a unique behavior or default note; nothing is repeated from the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values are covered externally. The description covers purpose, all three parameter semantics, defaults, and edge cases (wildcard, ignored parameter). Minor gaps remain — no statement about requiring an authenticated session (sibling kairos_login suggests it) and no error/pagination behavior — but nothing essential to calling the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate, and it does. Every parameter receives semantic detail beyond the bare schema: plan explains default resolution and wildcard semantics, bucket explains filtering plus its ignored-with-'*' interaction, and include_completed explains the 100% threshold and default. An agent cannot get this meaning from the schema, only from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('List Planner tasks') and a purpose ('so a task can be referenced or completed'). This clearly differentiates it from the sibling list_planner_plans (lists plans, not tasks) and from create_planner_task / complete_planner_task, so an agent can tell them apart on the description alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose clause implies workflow placement (list to get IDs, then complete), and the parameter notes define valid inputs. However, no alternative tool is named and there is no explicit when-to-use vs. when-not-to guidance, such as 'call list_planner_plans first to discover plan names.' Usage is inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0complete_planner_taskcreate_planner_bucketcreate_planner_taskkairos_auth_statuskairos_loginkairos_login_finishlist_planner_planslist_planner_tasksScored across 8 tools
Each tool maps to a distinct action/resource: auth bootstrap/finish/status, plan listing, task creation, bucket creation, task listing, and task completion. The two-step login flow is clearly sequenced, and there is no meaningful overlap between tools.
Most names follow a clear verb_noun snake_case pattern (list_planner_plans, create_planner_task, complete_planner_task). Minor inconsistency: auth tools use a kairos_ prefix while planner tools do not, and kairos_login_finish is a verb+adverb rather than a noun, but the overall pattern remains readable.
Eight tools is well-scoped for an authentication flow plus Planner task management. Each tool earns its place, and there are no redundant or overwhelming additions.
Core Planner workflows are covered: list plans, create buckets, create tasks, list tasks, and complete/reopen tasks. However, there is no way to update task details, delete a task or bucket, or fetch a single task in isolation, which leaves notable lifecycle gaps.
Permissioned access to Outlook, OneDrive and Teams via the user's own Microsoft account
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
