> ## Documentation Index > Fetch the complete documentation index at: https://docs.kowalah.com/llms.txt > Use this file to discover all available pages before exploring further. # Available tools > What each of the 26 connector tools does, what it returns, and how your role and your place in the org chart affect what you can see and change. The Kowalah connector exposes 26 tools, eleven that read and fifteen that write, grouped into seven jobs: keeping up with your programme, triaging opportunities and running discoveries, checking your own training, reading your AI Operating Model, maintaining it, keeping your systems register and AI estate, and recording the value AI has delivered. The same tools work in Claude, ChatGPT and the Kowalah Agent. Every tool is scoped to organizations you belong to and filtered by your role in each one, so you never see anything Kowalah hasn't given you access to in the platform. > **[Your programme](#your-programme)** > > Get an update, find an accelerator, raise an opportunity > **[Your training](#your-training)** > > What you're booked on, your agenda, how you're getting on > **[Reading the operating model](#reading-your-operating-model)** > > Your unit tree, one unit's portfolio, one process in full, and who's who > **[Changing the operating model](#changing-your-operating-model)** > > Edit what you own, propose changes to what you don't > **[Systems and AI estate](#your-systems-register-and-ai-estate)** > > The tools you run on, and the AI you've actually switched on > **[Outcomes](#outcomes)** > > Record and report the value AI has delivered ## Your programme ### `kowalah_get_update` A single tool for any "how are things", "what's the status of X", "what's waiting for me" question. Pass an optional natural-language query; the server figures out whether you want a portfolio rollup, a focused view of a specific thing, or just your identity and organizations. | You ask | You get | | - | - | | `What's going on in Kowalah?` (no query) | A **home view**, your role-appropriate rollup, plus any pending discovery invites | | `How's the procurement project?` | A **focused view** of the matched project, deliverable, Expert Request, or opportunity | | `What's ER-42 doing?` | A focused view of that Expert Request | | `Show me OPP-14` | A focused view of that opportunity | #### Pending discoveries in the home view If Kowalah is running a [Discovery](https://docs.kowalah.com/platform/discoveries.md) and you're on the audience, the home view includes a `pending_discoveries` section with: * The discovery number (e.g. `DISC-0003`) and name * The **goal**, what Kowalah is researching * The **business value context**, why it matters * The **close date**, when the discovery stops collecting responses * The **project** the discovery sits against (if any) You only see your own invite. You don't see other people's responses or Kowalah's internal triage. Pending discoveries are independent of your role: members, core team, and admins all see whatever they've personally been invited to. #### What a focused view returns | Entity | Includes | | - | - | | **Project** | Status, health, deliverables, milestones, client-visible risks and decisions, open Expert Requests, recent outcomes, your Kowalah contact | | **Deliverable** | Stage, progress, parent project, client-visible tasks, open Expert Requests, outcomes captured against it | | **Expert Request** | Status, progress, recent progress updates, outcomes, assigned expert contact | | **Opportunity** | Status, content, ICE score, source, what (if anything) it's been promoted to | ### `kowalah_find_accelerator` Searches Kowalah's global accelerator library plus your organization's private accelerators for a reusable prompt, GPT, training, or workflow. Use this whenever you're about to raise a request for help. There may already be something on the shelf you can take and run with. ```text theme={null} Is there a Kowalah accelerator for writing job descriptions? ``` Results often include a try-it-now prompt that Claude can act on directly inside the same chat. ### `kowalah_create_opportunity` The single inbound entry point for everything a customer wants to raise with Kowalah: a question, an idea, a piece of work to scope, a new project to consider. Anyone in your organization can submit, regardless of role. You don't have to decide whether the work is an [Expert Request](https://docs.kowalah.com/platform/expert-requests.md), a [Deliverable](https://docs.kowalah.com/platform/projects/deliverables.md), or a [Project](https://docs.kowalah.com/platform/projects/overview.md). Your organisation's AI lead (its admins and core team) triages it first, and Kowalah's team helps turn the shortlisted ones into work. Before submitting, Claude is expected to: 1. Check the accelerator library for something that already solves the problem 2. Make sure the description is at least a paragraph (\~80+ characters of real context: goal, what good looks like, anything Kowalah should know). The server rejects anything shorter 3. Capture an ICE score (impact, confidence, ease) with a reason for each 4. Where your organization has an AI vision map, name the guiding principle the opportunity serves and the KPI it moves 5. Ask which organization the opportunity is for (if you belong to more than one) #### Linking an opportunity to a discovery If you're responding to a Kowalah discovery you've been invited to, Claude passes the `discovery_id` through when it submits. The server then: * Validates that you're actually on the discovery's audience * Stamps the opportunity with the discovery and its project * Marks your audience invite as responded so reminders stop You'll see this happen automatically when you ask Claude to respond to a pending discovery. There's nothing extra you need to type. ## Triage and discoveries These tools let your organisation run its own backlog. Members can list the opportunities they raised; everything else here is for **admins and core team**. Each change is confirmed with you first, and a batch (a shortlist of ten, a merge list) is shown in full before anything changes. ### `kowalah_list_opportunities` Lists your organisation's opportunities, filtered by discovery, status and department, sorted by ICE score or date, and paged. Each row carries its department, ICE breakdown with a short reason per dimension, a summary, and what it was merged into or promoted to. Admins and core team see every opportunity; members see their own. ```text theme={null} List every opportunity from the Finance discovery, highest score first ``` Use this rather than an update for a workshop playback or a dashboard, because the update view stops at the newest 25. ### `kowalah_triage_opportunity` Records a triage decision: **shortlist**, **park**, **reject** (a reason is required, and the person who raised it sees it), **revert** to captured, **merge** a duplicate into another opportunity in the same discovery, or **rescore** any ICE dimension. Every score change is kept in the score history. Merging is final. ```text theme={null} Shortlist OPP-0142 and park OPP-0150 until after the ERP upgrade ``` ### `kowalah_promote_opportunity` Takes a captured, shortlisted or parked opportunity forward, the same choice as **Take it forward** in the platform: * **Your own project** creates a deliverable straight away, at the planning stage, on one of your projects or a new one. Needs the Business plan or Managed Services. Kowalah isn't notified. * **Ask Kowalah** sends a request for Kowalah to take it on as a deliverable on your Kowalah project. It waits as **Waiting for Kowalah** until Kowalah approves or declines it. The ICE score needs its reasons first: at least one Impact reason, plus a Confidence and an Ease reason. Expert Requests are raised in the platform. ### `kowalah_save_discovery` Creates and edits a discovery your organisation runs itself, under one of your own projects: the name, what you want to find out, the close date and the target number of ideas. It also adds and removes people from the audience, and closes a live discovery so it moves into triage. Needs the Business plan or Managed Services. Launching sends the invitation emails, so it happens in the platform: the tool returns a link to launch it. A discovery needs a goal, a close date and at least one person before it can launch. Discoveries Kowalah runs for you can't be changed here. ## Your training ### `kowalah_get_my_training` Your own [Kowalah training](https://docs.kowalah.com/training/overview.md) record: what you're booked on, your agenda for the day, and how you're getting on. ```text theme={null} What training am I booked on, and how did I do? ``` Pass a `kind` to choose the view: | `kind` | Returns | | - | - | | `enrolment` (default) | The programmes and events you're a participant in: titles, dates, location, your group, status | | `schedule` | Your day-by-day agenda, with sessions, times, rooms, and topics | | `progress` | Your attendance, module and quiz results, Claude Scale scores, badges, certificates, your feedback, and your commitments | | `org_overview` | An anonymised aggregate rollup for your organization. **Admin and core team only** | > [!NOTE] > > This tool only ever shows **your own** training, matched to you by Kowalah account or email address. It never exposes other participants, their results, the cohort roster, trainer notes, or anyone else's feedback. `org_overview` is counts and averages with no named individuals and no free-text comments; everyone else asking for it gets a not-permitted note. > > If you're enrolled but the tool says you aren't, the training may be registered against a different email address. Contact your Kowalah team. ## Reading your operating model These tools give Claude your [AI Operating Model](https://docs.kowalah.com/platform/operating-model/overview.md): the map of how your organization actually works, and how much of it AI could support. **Everyone in your organization can read the whole map**, whatever their role. ### `kowalah_get_operating_model` The world view. Returns your unit tree with coverage rollups on every node (coverage %, process count, redesign-gap count, constraint count, rolled up across each unit's whole subtree), plus org-wide totals and a narratable summary. ```text theme={null} How much of our business could AI support today, and where are the gaps? ``` Pass `organization_id` only if you belong to more than one organization. If nothing has been mapped yet, the tool says so rather than returning an empty tree. ### `kowalah_get_operating_model_unit` One unit in focus: its subtree coverage rollup, the processes it owns directly (each with its own rollup), its child units, and the top redesign-backlog steps across its processes, ranked by constraint and coordination burden. ```text theme={null} Show me the Finance function's processes and where the backlog is ``` ### `kowalah_get_process` One process in full, and the richest thing the connector returns. Includes: * Process metadata: purpose, cadence, criticality, owners, owning unit * Ordered steps with **current to target dispositions**, and gap and constraint markers * The **DEFINE contract** on each step: acceptance criteria, input artifact, output artifact * Per-step implementation links and per-step **quality evals**, with target versus current scores * A process-level rollup and the ranked redesign backlog * Inter-process **connections**, the handoffs and feeds touching this process * **Initiatives** already aimed at it, the opportunities, deliverables, and projects linked to the process or to one of its steps * The **systems** each step runs on, from your systems register, and the AI assets that run it * **Outcomes** recorded on the process and its steps, with totals that keep claimed apart from verified, and one-off apart from recurring * **Notes**: evidence, observations, decisions, and the open questions still to answer * A **diagnosis** of how well the process is captured. A missing measurement reads as "can't say", never as zero: the cycle ratio (work time over elapsed time) only appears when every step is timed The response also carries an `access` block telling Claude what *you* may do to this process, so it can offer the right next step rather than attempting an edit that gets refused. See [who can change what](#who-can-change-what). > [!TIP] > > Initiatives are filtered to what you personally may see, so this list can legitimately differ between two colleagues looking at the same process. ### `kowalah_get_vision` Your organization's [AI vision map](https://docs.kowalah.com/platform/operating-model/overview.md): the vision statement, its guiding principles with their defining attributes, and the success measures, with a baseline, a target, and a current reading where they've been set. Pass a unit to get the vision that unit inherits. ```text theme={null} What's our AI vision, and does this idea fit it? ``` The vision map is read-only through the connector. It's created with Kowalah at an AI Vision Day. ### `kowalah_find_person` Looks up people in your organization by name or email, partial and case-insensitive. Returns each person's name, email, home unit and the ID that owner fields take. This is how Claude sets an owner when you name one in conversation: a process owner, a step owner, an eval owner, a unit leader, or the owner of a system or AI asset. ```text theme={null} Make Sarah the owner of the approval step ``` Owners must be people in your organisation's operating model, but they don't need a Kowalah login. If more than one person matches, Claude asks which you mean. ### `kowalah_save_person` Adds someone to your operating model, or changes their name, email, position or home unit, or marks them as having left. Use it when an owner needs to be someone who isn't listed yet: Claude looks them up first and only adds them if nobody matches. **Admins only.** Adding an email doesn't invite them or give them a login; inviting happens on the People page in the platform. Someone marked as left keeps what they own until it's reassigned. ## Changing your operating model Reading the map is open to everyone. Changing it depends on where the thing you're changing sits relative to you, which the connector resolves on every call. If you can't edit something directly, the answer is never a dead end: it routes to a proposal. ### `kowalah_save_process` Creates or updates a process. On create, the process number is allocated automatically and the owner defaults to the owning unit's leader. On update, only the fields you provide change. You can re-parent a process to a different unit within the same organization. ### `kowalah_save_process_step` Creates or updates a step within a process. On create, position defaults to append and the current disposition defaults to `human`. A step's **platform** is the AI or automation that runs it, so a step a person does has none (a person working with AI help is `ai_assisted`). To record the tool a person does the step in, such as "manual today, in Ninety", keep the step human and add that tool to the step's **systems** from your [systems register](#your-systems-register-and-ai-estate). > [!WARNING] > > **The Jidoka rule.** If a step's target disposition is `ai_autonomous`, it must carry an escalation trigger: the stop-condition that hands control back to a human. A partial update that would leave a step autonomous without a trigger is rejected. This is enforced by the server, not just the UI. ### `kowalah_save_process_step_eval` Creates or updates an eval on a step: the quality check that its output meets its acceptance criteria. This is how a business owner sets and tracks the bar, for example "what counts as a good forecast category call" or "what a compliant response looks like". * A **gate** blocks the step until it passes. It's all-or-nothing and cannot carry a sampling percentage. * A **monitor** observes a sample, and may set a sampling percentage from 0 to 100. * `target_score` is the bar; `current_score` and `measured_at` record the latest reading. Creating an eval needs edit rights on the parent process. Once it exists, **the eval's owner can keep editing it** even if the process itself sits above their altitude, so a function lead can own the quality bar on a process they don't otherwise control. ### `kowalah_save_org_unit` Creates or updates a node of your org-unit tree. For a child unit, pass a parent; the organization is inherited. Creating a **root** unit reshapes the top of the org chart and is restricted to admins and core team. ### `kowalah_save_process_connection` Creates, updates, or removes a connection between two processes: a handoff ("qualified deals pass to Proposal") or a feed. Connections are what make the operating model a map of how work moves rather than a list. Because a connection touches both processes, you need edit rights on both ends. ### `kowalah_propose_redesign` Creates a **to-be** version of a process beside the original, so the two can be compared. It starts from the as-is and from the redesign decisions already marked on its steps: steps marked eliminate or merge don't come across, and a step with no decision is carried rather than dropped. The original process isn't changed, and you can put more than one option side by side. ### `kowalah_propose_process_change` The route when you can't edit directly. Instead of changing the process, it files an [Opportunity](https://docs.kowalah.com/platform/opportunities.md) linked to that process, and optionally pinned to one step, so the owner can pick it up. ```text theme={null} This approval step should be automated, raise that with whoever owns it ``` Use it for "this step should be automated", "the acceptance criteria here are wrong", "we should add a quality gate", anything you would change if it were yours. **Anyone in the organization can propose against any process they can see**, and nothing about the process itself is modified. ## Who can change what Your ability to edit the operating model is governed by your **altitude**: where the target sits relative to your home unit in the org tree. This is a different axis from your role, which governs what you can *see*. | Your relationship to the target | Edit in place | Create here | Propose | | - | - | - | - | | You **own** it | Yes | Yes | Not needed | | It's **below** your unit | Yes | Yes | Not needed | | It's **at** your unit, someone else owns it | No | Yes | Yes | | It's **above** you | No | No | Yes | | **Unrelated** branch, or you have no home unit | No | No | Yes | > [!NOTE] > > **Admins and core team are cross-cutting editors** within their own organization: they can edit and create anywhere in it. Being an admin in one organization confers nothing in another. > > If no home unit has been set for you, everything resolves to the safe default of read and propose. Ask your organization admin to set your home unit if you should be able to edit. Because `kowalah_get_process` returns your resolved `access` up front, Claude can offer "shall I change that, or propose it to the owner?" rather than trying an edit and reporting a refusal. > [!NOTE] > > Projects, deliverables, Expert Requests, contracts, and existing opportunities are read-only through the connector, whatever your altitude or role. Processes, steps, evals, units, systems, and AI assets are **never deleted** (steps, systems, and AI assets are archived instead). The only removals are narrow: a connection between two processes, an arrangement on a system (admins and core team), and an outcome, which is soft-deleted. Each is recorded in the model's history. ## Your systems register and AI estate The **systems register** is the tools and platforms your work runs on, whether each has AI in it, and how your organization holds it. The **AI estate** is what has actually been built and switched on in them: connectors, skills, plugins, projects, agents, automations, and apps. Everyone in the organization can read both. ### `kowalah_get_systems` Every system with its **arrangements**: the ways your organization holds it (tier, seats, who the contracting party is, whether there's a DPA, whether it trains on your data, admin control, audit trail, and sanctioned status). One system often has several, for example a company plan alongside personal plans people pay for themselves. ```text theme={null} What AI tools do we have, which are unsanctioned, and what renews soon? ``` The register flags what to act on: unreviewed arrangements, risks such as employee-contracted tools with no DPA, AI systems with no arrangement recorded, systems no process step uses, and renewals due in the next 90 days. Commercial fields (cost, payment route, renewal date) are shown to admins and core team only. ### `kowalah_save_system` Adds or updates a system and its arrangements. **Admins and core team only.** Kowalah's shared catalogue systems can't be edited, but you can record your own arrangements on them. A field you leave unset means "not assessed", which is different from "no". ### `kowalah_get_ai_estate` Every AI asset recorded, with its platform, owner, status, scope, who has used it and where, the process steps it runs, and the outcomes it produced. It leads with the gaps: assets with no owner, undecided ones, ones nobody has used for 90 days, connectors that can act with nobody approving, people holding a lot of connections, personal assets, and **shadow AI** running on a platform your organization hasn't approved. ```text theme={null} What AI have we actually got, and what's running without anyone approving it? ``` ### `kowalah_record_ai_assets` Records the AI tools someone's assistant session uses, and what they say about each one. It works from Claude, ChatGPT and Codex, and the register is ready for Microsoft Copilot and Gemini. Your assistant shows you the list before saving, and records only what you agree to share. Each tool is put on the platform the session runs on, such as Claude or ChatGPT, when your systems register holds it. If the register doesn't, the tool is recorded with no platform and shown as a gap for your AI lead to fill, never filed under the wrong system. > [!NOTE] > > Only **names and identifiers** are recorded: never a skill's instructions, a prompt, a tool description, or a project's contents. Anyone can mark something as their own personal asset; admins and core team decide everything else about an asset. ## Outcomes ### `kowalah_save_outcome` Records realised value, such as time saved, cost reduced, revenue won, or an adoption milestone, on any work: a process step, a process, a unit, an opportunity, the whole organization, or a Kowalah deliverable or Expert Request. An outcome can say which AI asset produced it and which vision measure it counts towards. ```text theme={null} The quote drafter saves the estimators about 12 hours a week. Record that. ``` * **Anyone** can record an outcome. It's recorded as a **claim**, with how the figure was arrived at: estimated, sampled, or measured. * **Admins and core team** can verify an outcome, in their own name. Changing a verified figure makes it a claim again. * A figure carries a comparable unit (hours, count, percent, or a currency) so outcomes can be added up. * Removing an outcome is a soft delete. ## Confirmation before changes Tools that change or remove existing data are marked as destructive, so Claude asks you before running them: the four `save` tools for the operating model, process connections, the systems register, the AI estate, and outcomes. Tools that only add something new, such as raising an opportunity, proposing a change, or proposing a redesign, run without that extra step. ## Prompts The connector also registers a few **prompts** you can pick from Claude's prompt menu (the "+" attachment or slash menu, depending on which Claude client you're using). Some are role-gated. | Prompt | Who sees it | What it does | | - | - | - | | **Submit an opportunity** | Everyone | Guided coaching flow that walks you through goal, what good looks like, and context, then submits the opportunity. Accepts an optional one-line idea, and an optional discovery ID if you're responding to a brief | | **Programme update** | Admin and core team only | Pulls a structured programme update across your portfolio | | **Expert Request credits and quota** | Admin and core team only | Summarises Expert Request credits used vs. quota under each active contract | Members don't see **Programme update** or **Expert Request credits and quota** in the prompt menu. They're only registered for privileged roles. ## Resources Alongside tools, the connector exposes your accelerators, opportunities, projects, deliverables, and Expert Requests as MCP **resources**, so Claude clients that support resource browsing can attach them to a conversation directly. Resources are filtered by exactly the same rules as the tools, and the filter is re-checked on read, so a hand-typed identifier can't bypass it. ## What your role changes Role governs **visibility**. Altitude, above, governs **editing**. | Role | Update view | Opportunities visible | Projects, deliverables, ERs visible | Operating model | Can raise opportunities | | - | - | - | - | - | - | | **Admin** | Full org rollup | Every opportunity in the org | All | Read all, edit anywhere in the org | Yes | | **Core team** | Full org rollup | Every opportunity in the org | All | Read all, edit anywhere in the org | Yes | | **Member** | Personal rollup | Only the ones **you** raised | Only the ones you're a **stakeholder** on | Read all, edit by altitude | Yes | A `no_match` response for a known reference number usually means the item exists but you're not permitted to see it, not that it doesn't exist. This is most common for members who aren't on the stakeholder list for a given project, deliverable, or Expert Request. A few things are different: * **Discovery invites** are personal to you, so you always see your own pending discoveries regardless of role. * **Training** is personal to you: everyone sees their own record only, and only admins and core team can pull the anonymised org rollup. * **The systems register** is readable by everyone, but only admins and core team can change it or see its commercial fields. * **Outcomes** can be recorded by anyone, and verified only by admins and core team. ## Data filtering The connector enforces visibility on the server side: * **Organization scoping**, only data from organizations you belong to is ever returned * **Role-based filtering**, members only see what they raised or are a stakeholder on * **Altitude gating**, operating-model writes are checked against your position in the org tree, after org scoping * **Client visibility flags**, tasks, risks, and decisions are filtered to client-visible items * **Discovery audience gate**, opportunity submissions tagged with a `discovery_id` are rejected if you're not on the audience * **Identity scoping**, training data is matched to you personally by account or email * **Field filtering**, internal fields (Kowalah team assignments, contract values, payment details) are not exposed, and Kowalah-side ownership can't be set by a client even on records you create > **[Set up in Claude](https://docs.kowalah.com/plugin/setup-claude.md)** > > Add the connector to your Claude workspace > **[Work your operating model in Claude](https://docs.kowalah.com/plugin/operating-model.md)** > > Map, review, and improve processes in conversation > **[Roles and permissions](https://docs.kowalah.com/platform/organization/roles-and-permissions.md)** > > Full role reference > **[Security and data access](https://docs.kowalah.com/security/data-and-access.md)** > > How the connector is scoped and gated This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.