> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komodor.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Use cases
> The typed actions an agent advertises — each becomes a callable tool on that agent's own MCP endpoint, with its own input and output schema.
An agent can do more than answer a prompt. A **use case** is a named, schema-typed action the agent
advertises — *triage a build*, *run a backup* — and the Komodor Agentic Operation Platform (KAOP)
turns each one into a callable tool on that agent's own endpoint. This page covers what a use case
is, how it differs from two things it is easily confused with, how you declare one, and the two
every agent gets for free.
## It is not a skill, and not a capability flag
These three sit close together and do different jobs. Mixing them up is the usual mistake.
| | What it is | Who reads it |
| ------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| **Use case** | An invocable, schema-typed action with its own input and output | Something calling the agent from outside |
| **Skill** | An instruction document — a runbook or procedure | The agent itself, while it works |
| **Capability flag** | A boolean on the agent card (`chat`, `review`, `grader`) saying what class of work the agent accepts at all | The platform, when it routes work |
A skill shapes *how* the agent works. A capability says *what class of work* it takes. A use case is
an *entry point someone else can call*.
## Declaring one
Use cases live in the worker's `agent-spec.yaml`, and the agent advertises them itself — there is
nothing to register separately.
```yaml theme={null}
use_cases:
- slug: triage_build
description: Triage a failed CI build and summarize the likely cause.
input_schema:
type: object
properties:
build_id: { type: string }
required: [build_id]
output_schema:
type: object
properties:
cause: { type: string }
timeout_seconds: 300
- slug: run_backup
description: Run an on-demand backup.
timeout_seconds: 120
```
| Field | Required | What it means |
| ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `slug` | yes | The stable identifier, and the tool name. Lowercase letters, digits, `_` or `-`; starts and ends alphanumeric; 64 characters or fewer; unique within the agent. |
| `description` | yes | Becomes the tool's description, read by both people and models. Write it as an instruction, not a label. |
| `input_schema` | no | JSON Schema for the input. Leave it out and the use case takes free text. |
| `output_schema` | no | JSON Schema for the result. Leave it out and the result is free text. |
| `timeout_seconds` | yes | 1–3600. How long a blocking call waits for the worker to get a slot and finish. Keep it below any load-balancer idle timeout in front of the caller. |
A malformed spec is rejected when you author it rather than at run time, and the same definition is
the wire format — there is no second place for it to drift.
Use cases travel inside the agent card, so changing them registers as a new generation of the agent.
There is nothing separate to publish.
## Every agent already has two
Both are advertised automatically, so a freshly deployed agent always has a safe command you can run
to prove it works.
| Use case | What it proves |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Check connectivity** | A canned, deterministic reply with **no model, no tools, no integrations** — it short-circuits before your handler runs, so it always succeeds. It proves the platform can reach the worker and that runs and transcripts are flowing. This is what the one-click check runs. |
| **Sample run** | A **real** run through your actual handler and model, with a canonical self-introduction prompt, producing a live transcript. It proves the whole path including the model. |
Declaring your own `connectivity_check` or `sample_run` keeps your definition instead.
When a newly deployed agent looks wrong, run these in order. **Check connectivity** failing points at
deployment or networking; **Check connectivity** passing while **Sample run** fails points at the
model, the tools, or the handler.
## Calling one
Every agent is served as its own MCP server, so a client can connect to that one agent:
```json theme={null}
{
"mcpServers": {
"buildkite-triage": {
"url": "https:///agent-mcp/buildkite-triage/mcp",
"headers": { "Authorization": "Bearer " }
}
}
}
```
Alongside your declared use cases, every agent exposes two universal tools:
* **`invoke`** — starts a run. It is typed from the agent's own input schema when it has one, and
otherwise takes free text. It also accepts a `use_case` field, so calling `invoke` with
`use_case: "triage_build"` reaches exactly the same path as calling `triage_build` directly.
* **`get_run`** — checks a run that `invoke` started. Given a run id it reads the current state; give
it a wait and it blocks for up to 45 seconds instead of returning immediately.
Declared use cases are additive: a typed agent keeps its own tools **and** gets these two.
The agent's **Metadata** tab carries the connection details for this endpoint — the URL, a ready-made
client command, and the use cases it publishes.
## Next steps
Where `agent-spec.yaml` lives, and the rest of what it declares.
The know-how an agent reads, as opposed to an entry point it offers.
The platform's own MCP surface, distinct from an agent's.
Getting to the point where there is something to call.
## Related topics
- [Python SDK](/developer-tools/python-sdk.md)
- [Go SDK](/developer-tools/go-sdk.md)
- [AWS Cost Analyzer](/manage-your-agents/build/catalog/aws-cost-analyzer.md)
- [Use specialized agents](/manage-your-agents/build/use-specialized-agents.md)
- [Install](/get-started/on-prem/install.md)