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., "@olivetin-mcp restart the Nginx server"
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.
Community-maintained Python implementation. Not affiliated with or endorsed by the OliveTin project.
A hardened MCP server that exposes OliveTin actions as tools, with built-in human-in-the-loop approval for destructive operations.
claude mcp add olivetin -e OLIVETIN_URL=http://localhost:1337 -- uvx --from git+https://github.com/vaddisrinivas/olivetin-mcp.git olivetin-mcpAI agents (Claude, GPT, etc.) are increasingly capable of running shell commands and managing infrastructure. But there's a fundamental trust gap:
Without approval gates, an agent can rm -rf /, restart production, or leak secrets — and you only find out after the damage is done.
Without action discovery, agents guess at commands instead of using your pre-defined, parameterized, tested actions.
Without audit trails, you can't answer "what did the agent do and why?"
Giving an AI agent a raw shell is like giving a new hire root access on day one. You wouldn't do it. Instead, you'd give them a runbook of approved actions and require sign-off for anything destructive. That's exactly what this project does.
OliveTin is the runbook — safe, parameterized shell actions with a web UI. olivetin-mcp is the bridge that lets AI agents use that runbook, with human approval built in.
Related MCP server: Agentrim MCP
OliveTin lets you define shell commands as safe, parameterized actions with a web UI. olivetin-mcp bridges those actions into the Model Context Protocol so Claude (or any MCP client) can discover and execute them — with automatic human approval gates for anything destructive.
Without this bridge: Claude can't see or trigger your OliveTin actions. You'd need to manually copy-paste commands or build custom integrations.
With this bridge: Claude discovers all your actions automatically, validates arguments, and asks for human approval before running anything dangerous.
Approach | Pros | Cons |
Direct shell via Claude | Simple, no setup | No action discovery, no approval gates, no audit trail |
OliveTin Web UI alone | Built-in approval UI | No AI integration, manual operation only |
OliveTin API directly | Full control | Manual auth, no MCP schema, no standardized discovery |
olivetin-mcp (this) | Auto-discovery, approval chain, hardened container, MCP standard | Requires MCP client + OliveTin |
┌──────────────┐ SSE ┌──────────────────┐ REST API ┌──────────────┐
│ MCP Client │ <──────────────> │ olivetin-mcp │ ──────────────────> │ OliveTin │
│ (Claude, etc)│ port 9003 │ (this server) │ port 1337 │ (host) │
└──────────────┘ └──────────────────┘ └──────────────┘
│
v
┌──────────────┐
│ Approval UI │
│ /pending/:tok │
└──────────────┘Discovers OliveTin actions and registers each as an MCP tool
Classifies actions as read-only or destructive based on naming conventions
Gates destructive actions behind a two-step approval chain:
MCP native elicitation (inline dialog in Claude Code / Claude Desktop)
URL-based approval (human visits /pending/<token> to approve or deny)
Executes approved actions via the OliveTin REST API
Exposes resources for action catalogs, execution logs, and pending approvals
Comprehensive OliveTin API coverage (actions, logs, execution status, kill)
Three authentication modes (reverse-proxy headers, JWT, HTTP Basic)
Built-in static tools: brave_search, render_diagram, render_chart
Rate limiting per action
Structured logging with structlog
Retry with exponential backoff via tenacity
Security headers on all HTML responses
/healthz health check endpoint
Python 3.11+
OliveTin running and accessible — Installation guide | GitHub | Discord
claude mcp add olivetin -e OLIVETIN_URL=http://localhost:1337 -- uvx --from git+https://github.com/vaddisrinivas/olivetin-mcp.git olivetin-mcpThis installs and runs via stdio transport. For SSE (Docker), see below.
docker build -t olivetin-mcp .
docker run -d \
-p 9003:9003 \
-e OLIVETIN_URL=http://host.docker.internal:1337 \
olivetin-mcpA docker-compose.yml is included for running olivetin-mcp alongside OliveTin:
docker compose up -dpip install olivetin-mcp
python -m maingit clone https://github.com/vaddisrinivas/olivetin-mcp.git
cd olivetin-mcp
pip install -e ".[test]"
python main.py # stdio (for claude mcp add)
python main.py --sse # SSE server on port 9003 (for Docker)# Via uvx (no install needed):
claude mcp add olivetin -e OLIVETIN_URL=http://localhost:1337 -- uvx --from git+https://github.com/vaddisrinivas/olivetin-mcp.git olivetin-mcp
# Or if installed locally:
claude mcp add olivetin -- olivetin-mcpFor SSE mode (Docker), add to your claude_desktop_config.json:
{
"mcpServers": {
"olivetin": {
"url": "http://localhost:9003/sse"
}
}
}claude mcp add olivetin --transport sse http://localhost:9003/sseAll configuration is via environment variables. Copy .env.example to .env to get started.
Variable | Default | Description |
|
| MCP SSE server port |
|
| OliveTin API URL |
|
| Seconds to wait for approval decision |
|
| Public URL for approval links (e.g. |
|
| MCP elicitation dialog timeout |
|
| Docker secrets mount path |
|
| Action catalog refresh interval |
Pick one mode depending on your OliveTin setup:
Reverse-proxy headers (e.g. Authelia, Authentik):
OLIVETIN_REMOTE_USER=serviceaccount
OLIVETIN_REMOTE_GROUPS=admins,operators
OLIVETIN_USER_HEADER=X-Remote-User # optional, default shown
OLIVETIN_GROUPS_HEADER=X-Remote-Groups # optional, default shownJWT bearer token:
OLIVETIN_JWT_TOKEN=eyJhbGci...
# or mount as /run/secrets/olivetin_jwt_tokenHTTP Basic auth:
OLIVETIN_BASIC_USER=admin
OLIVETIN_BASIC_PASS=changemeThis project is designed to be run as a hardened container:
Non-root user (bridge:10001) with no login shell
Stripped attack surface: all shells, network tools, and compilers removed
No runtime pip: package manager removed after build
Read-only filesystem: designed for read_only: true in Docker Compose
Dropped capabilities: all Linux capabilities can be dropped
Human-in-the-loop: destructive actions require explicit approval
XSS protection: Jinja2 autoescape=True on all templates
Cryptographic tokens: approval tokens via secrets.token_urlsafe(16)
Security headers: X-Frame-Options, CSP, X-Content-Type-Options on all HTML responses
SSRF protection: diagram specs checked for disallowed URI schemes
See SECURITY.md for vulnerability reporting and threat model.
Each OliveTin action is registered as an MCP tool. Read-only actions (prefixed with [read-only] or ro_ binding ID) execute immediately. All others go through the approval chain.
Tool | Description |
| List all actions with schemas and approval status |
| Recent execution history |
| Status of a running execution |
| Kill a running execution |
| Force refresh the action catalog |
| Show pending approval queue |
| Web search via Brave Search API |
| Render Mermaid/PlantUML/D2 diagrams |
| Render charts via QuickChart |
URI | Description |
| Full action catalog (JSON) |
| Detailed action documentation |
| Recent execution history |
| Action-specific logs |
| Pending approval queue |
Here's how OliveTin actions map to MCP tools:
# In your OliveTin config.yaml
actions:
# This action executes immediately (no approval) because of [read-only] prefix
- title: "[read-only] Get Service Status"
shell: docker ps --format 'table {{.Names}}\t{{.Status}}'
# This action requires human approval before execution
- title: Deploy Service
shell: cd /srv/{{ service }} && docker compose pull && docker compose up -d
arguments:
- name: service
type: ascii_identifier
choices:
- value: api
- value: web
- value: workerQ: Claude shows the action but gets "Could not reach OliveTin"
Verify OliveTin is running: curl http://your-olivetin:1337/api/GetDashboard -X POST -d '{}'
If using Docker, ensure network connectivity (use http://host.docker.internal:1337 on Docker Desktop, or the container network name in Docker Compose)
Check OLIVETIN_URL env var
Q: Actions require approval but I want some to be read-only
Prefix the action title with [read-only] or the binding ID with ro_ in your OliveTin config. The bridge automatically classifies these as safe.
Q: Approval links don't work / show "Not Found"
Set APPROVAL_BASE_URL to the publicly reachable URL of the bridge (e.g. http://192.168.1.10:9003). The default localhost only works when the browser is on the same machine.
Q: MCP client times out waiting for approval
The default approval timeout is 120 seconds. Increase APPROVAL_TIMEOUT_SECS if needed. The elicitation dialog (inline in Claude) times out after 30 seconds (ELICITATION_TIMEOUT_SECS) before falling back to URL-based approval.
Q: Actions aren't showing up in Claude
Check the bridge logs for actions_loaded — it should show the count
Run the reload_actions tool to force a refresh
Verify OliveTin has actions configured and they aren't marked hidden: true
Q: How do I use Brave Search?
Mount the API key as a Docker secret at /run/secrets/brave_api_key, or set BRAVE_API_KEY in your environment. Get a key at brave.com/search/api.
Single maintainer: Bus factor of 1. See GOVERNANCE.md for co-maintainer path.
No end-to-end encryption: Communication between this bridge and OliveTin is HTTP by default. Use HTTPS in production or keep them on the same host/network.
Approval UI is basic: The URL-based approval page has no authentication beyond the cryptographic token. Anyone with the link can approve/deny. Keep approval URLs private.
Not a security boundary: This bridge adds an approval layer, but it trusts OliveTin's API. If OliveTin is compromised, the bridge can't protect you.
Young project: This is v0.1.0. Expect rough edges. File issues.
OliveTin — The automation platform this bridge connects to. Written in Go by James Read. Docs | Discord
Model Context Protocol — The open standard for AI tool integration. Spec | GitHub
FastMCP — The Python MCP framework this server is built on.
OpenClaw — Another approach to AI agent orchestration (different architecture).
The motivation: routing AI agents through OliveTin's pre-defined, parameterized actions is fundamentally safer than giving agents raw shell access. The approval chain ensures a human is always in the loop for anything destructive.
# Install all extras
make install
# Run all CI checks locally
make ci
# Or individually:
make test # pytest with coverage
make lint # ruff check
make type # mypy
make format # auto-formatSee CONTRIBUTING.md for more details, and ARCHITECTURE.md for codebase overview.
Search the web using the Brave Search API. Returns top results with title, URL, and description. No approval needed — read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond the readOnlyHint annotation by mentioning 'No approval needed' and the return format (top results with title, URL, description). This provides useful behavioral details about the tool's safety profile and expected output, without contradicting the annotation.
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 concise and front-loaded, stating the purpose in the first phrase. Every sentence adds value: the API source, the return fields, and the approval/read-only status. No unnecessary words.
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 2-parameter tool with an output schema present, the description is complete. It clarifies the tool's purpose, output shape, and approval requirements. There is no missing critical context that would hinder an agent from using the tool 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 schema has no parameter descriptions (0% coverage), so the description must compensate. The description implies that 'query' is the search string and 'count' limits the number of top results, but it does not explicitly define these parameters. The parameter names are self-explanatory enough for basic use, but the description could add more explicit semantics.
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 tool's function: 'Search the web using the Brave Search API.' It specifies the resource (web via Brave), the action (search), and the return format (top results with title, URL, and description). This distinguishes it from the unrelated sibling tools, which focus on server management and execution.
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: whenever a web search is needed. It also states 'No approval needed — read-only,' which serves as a guideline for invoking it without approval workflows. While it does not explicitly name alternatives or exclusions, the sibling tools are unrelated, so the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single OliveTin action binding by ID (GetActionBinding RPC). Returns full Action proto including arguments, icon, timeout, and ACL fields. No approval needed — read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| binding_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description reinforces this with 'read-only' and adds 'No approval needed'. It also discloses the return contents (full Action proto with arguments, icon, timeout, ACL fields), which is useful behavioral context beyond the annotation.
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 sentences, front-loaded with the core action and resource, then a concise mention of return details. Every sentence earns its place with no fluff.
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 read tool with one parameter and an output schema, the description covers the essential context: it fetches a single binding, lists return fields, and notes no approval is needed. The output schema handles return structure details.
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% for the single parameter binding_id. The description only says 'by ID', which adds no meaning beyond the parameter name. It does not explain where to find the ID or any format constraints, so it fails to compensate for the lack of schema 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 uses a specific verb ('Fetch') and resource ('OliveTin action binding') with scoping by ID. It clearly distinguishes from sibling tools like list_olivetin_actions by indicating it fetches a single binding. The mention of the RPC name and return type reinforces the 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?
The description implies when to use: when a single action binding is needed by its ID. It does not explicitly name alternatives or exclusions, but the context is clear. Since it doesn't explicitly say 'use this instead of list_olivetin_actions', it lacks an explicit exclusions statement, aligning with a score of 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all OliveTin entities (GetEntities RPC). Entities represent monitored services/hosts. No approval needed — read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, so the 'read-only' phrase is redundant, but the description adds 'No approval needed' and explains what entities represent (monitored services/hosts), providing context beyond the annotation.
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 concise sentences with the key action front-loaded. No unnecessary words; every element contributes to understanding.
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 the simplicity (no params, output schema present, no nested objects), the description fully covers purpose, safety, and semantics. It is complete for an agent to invoke 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?
With zero parameters, schema coverage is trivially 100%. The description adds no parameter details because none exist. Baseline 4 is appropriate for a no-parameter tool.
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' with a clear resource 'OliveTin entities' and differentiates from the singular sibling 'get_entity' by noting it lists all entities. The RPC name adds precision.
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 clearly states this is a read-only operation requiring no approval, which helps an agent choose it for safe listing tasks. It does not explicitly mention alternatives like 'get_entity' for single entities, but the plural 'all' implies the scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single OliveTin entity by unique key and type (GetEntity RPC). No approval needed — read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | ||
| unique_key | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, but the description adds that 'No approval needed', which is a useful behavioral trait beyond the annotation. It reinforces read-only behavior and mentions the RPC, providing extra context without contradicting the annotations.
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 a single, front-loaded sentence with no unnecessary words. It efficiently conveys the action, target, parameters, and safety profile in one line.
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 tool is simple and has an output schema, so return values are covered. The description covers the essential invocation details (unique key, type, read-only). It doesn't explain what an OliveTin entity is, but given the output schema and annotations, the information is sufficient for a basic understanding.
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 compensate, but it only restates the parameter names ('by unique key and type') without explaining their meaning, constraints, or the empty default for type. Minimal value is added over the schema.
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 tool fetches a single OliveTin entity by unique key and type, using a specific verb (Fetch) and resource. It distinguishes from the sibling get_entities by explicitly saying 'single', and references the GetEntity RPC for precision.
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 implies usage for single-entity lookup and mentions that no approval is needed, giving clear context. However, it doesn't explicitly contrast with the 'get_entities' sibling or other alternatives, so it lacks an explicit exclusion, but the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recent OliveTin execution history (LogEntry records). Proto fields: datetime_started, action_title, output, exit_code, timed_out, user, execution_tracking_id, blocked. No approval needed.
| Name | Required | Description | Default |
|---|---|---|---|
| action_id | No | ||
| page_size | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint: true, the description adds context beyond the annotation by clarifying that no approval is needed and enumerating the returned proto fields. This gives the agent useful behavioral and data-level information without contradicting the annotation.
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 with the primary action and resource. The additional details about proto fields and approval status are useful and concise, with no extraneous wording.
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 tool has an output schema and readOnly annotation, so the description need not explain return structure. It covers the main purpose and added context, but it misses parameter semantics, which would make it fully complete for a tool with two parameters and zero schema descriptions.
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 compensate, but it does not explain the purpose of action_id or page_size. The parameter names are self-explanatory to some degree, but the description lists only output fields, leaving input parameters ambiguous.
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 verb 'Get' and the resource 'OliveTin execution history (LogEntry records)', which is specific and unambiguous. It differentiates from siblings like get_execution_status and list_olivetin_actions by naming the domain as execution history.
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 implies use for retrieving execution history but does not explicitly state when to use this over alternatives, nor any exclusions or prerequisites. 'No approval needed' provides an authorization note but does not offer comparative usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the status of a running OliveTin action by its execution_tracking_id (returned by StartAction). No approval needed.
| Name | Required | Description | Default |
|---|---|---|---|
| execution_tracking_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds relevant context that no approval is needed, which is not captured by annotations. No contradiction.
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?
A single concise sentence that conveys purpose and key usage context without unnecessary words.
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 1-parameter read-only tool with an output schema, the description covers the core actions, parameter source, and approval requirement. Nothing critical 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%, but description explains the parameter's origin (returned by StartAction), providing meaning beyond the raw schema definition of a string.
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?
States the specific verb 'Check' and resource 'status of a running OliveTin action', with clear reference to execution_tracking_id. This distinguishes it from siblings like get_execution_logs and kill_action.
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?
Implies usage for checking status when an execution_tracking_id is available from StartAction, and notes 'No approval needed.' Lacks explicit exclusion of alternatives, but context is clear given sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return OliveTin server info and version (Init RPC). No approval needed — read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already declares readOnlyHint=true, so the description's 'read-only' is redundant. However, adding 'No approval needed' gives extra behavioral context beyond the annotation, which is useful. The phrase 'Init RPC' also hints at technical behavior.
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 a single, front-loaded sentence that conveys purpose, approval requirements, and read-only nature without any unnecessary words.
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 getter with no parameters and an existing output schema, the description is complete. It covers what the tool returns, its read-only nature, and the fact that approval is not needed.
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 input schema is empty. Baseline for no parameters is 4, and the description does not need to elaborate on parameter details since there are none.
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 tool returns OliveTin server info and version, with a specific verb and resource. It distinguishes itself from siblings that perform actions like restart or kill, though it doesn't explicitly name an alternative.
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 implies this is a simple read-only getter and highlights that no approval is needed, but it does not explicitly state when to prefer this tool over others or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Kill a currently running OliveTin action by its execution_tracking_id. Only works when the LogEntry's can_kill field is true. Returns killed/already_completed/not_found status. No approval needed — this is a safety stop, not a destructive write.
| Name | Required | Description | Default |
|---|---|---|---|
| execution_tracking_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description directly contradicts the annotation readOnlyHint=true. Killing an action is a state-changing operation, not read-only. The description attempts to reframe it as a safety stop, but it still modifies execution state, so this is a serious inconsistency.
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 focused sentences, front-loaded with the action, and contains no unnecessary information. Every sentence adds value regarding either the precondition, outcome, or safety posture.
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 core behavior, precondition, return statuses, and clarifies safety. However, it does not explain how to obtain the execution_tracking_id, and the annotation contradiction creates ambiguity. The presence of an output schema partially offsets the need to describe return values in detail.
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 single parameter execution_tracking_id is explained in the description as the identifier used to kill the action. It also adds context about the action needing to be running and references the can_kill field, which compensates for the 0% schema description coverage.
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 tool's purpose: "Kill a currently running OliveTin action by its execution_tracking_id." It uses a specific verb ("kill"), identifies the resource ("currently running OliveTin action"), and distinguishes it from sibling tools like restart_action or get_execution_status.
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 a clear precondition: "Only works when the LogEntry's can_kill field is true." It also explains the outcome statuses, but it doesn't explicitly mention alternatives or exclusions relative to sibling tools, so it stops short of a full guidance score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available OliveTin actions: IDs, titles, argument schemas, and whether each requires approval. No approval needed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only include readOnlyHint=true, but the description adds value by disclosing the output content (IDs, titles, argument schemas, approval flags) and explicitly stating 'No approval needed' for the call itself. This goes beyond the read-only hint and gives the agent confidence about side-effect-free behavior and operational prerequisites.
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 concise, consisting of two short sentences. It front-loads the core purpose ('List all available OliveTin actions') and packs useful specifics (what fields are returned, no approval needed) without any filler or repetition. Every sentence earns its place.
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 the tool's simplicity (no parameters, read-only, no side effects), the description covers all essential information: the action scope ('all'), the list of returned fields, and the absence of an approval requirement. An output schema exists, so return value details need not be repeated. This is complete for an agent to use 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 and an empty input schema, so the schema description coverage is trivially 100%. The baseline for zero parameters is 4, and the description does not introduce any parameter-related confusion. It appropriately focuses on the output rather than nonexistent inputs.
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 tool lists all OliveTin actions and specifies the exact information returned (IDs, titles, argument schemas, approval requirements). The verb 'list' is specific, the resource 'OliveTin actions' is unambiguous, and it distinguishes itself from sibling tools like list_pending_approvals.
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 this tool: to discover available actions and their properties. It does not explicitly exclude alternatives or name them, but the purpose is self-evident and the added note 'No approval needed' signals that this operation is safe and callable without restrictions. This is clear context without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all OliveTin actions currently waiting for human approval, with the URL the human must visit to approve or deny. Call this after triggering a destructive action to get the approval link. No approval needed — read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint:true already indicates safety, but the description reinforces this with 'No approval needed — read-only' and adds useful behavioral detail about the output: each entry includes the approval URL. This goes beyond the annotation by clarifying exactly what data is returned.
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, front-loaded with the core purpose, then a usage note and safety clarification. Every sentence adds value with no redundancy or fluff.
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 fully covers what the tool lists, what information it provides (approval URL), when to call it, and its read-only nature. With an output schema present and no parameters, nothing important is missing for this simple tool.
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 is an empty object. The baseline for 0 params is 4, and no parameter explanation is needed. The description does not attempt to add param semantics, which is appropriate.
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 tool's purpose: 'List all OliveTin actions currently waiting for human approval, with the URL the human must visit to approve or deny.' It uses a specific verb and resource, and the focus on 'pending approvals' distinguishes it from the sibling tool 'list_olivetin_actions'.
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 provides explicit usage context: 'Call this after triggering a destructive action to get the approval link.' This tells the agent when to use the tool, though it does not mention alternatives or exclusions. The guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
OliveTin readiness probe (GetReadyz RPC). Returns 200/ready when OliveTin is healthy. No approval needed — read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true; the description adds beyond that by mentioning 'No approval needed' and specific response behavior ('Returns 200/ready'), giving useful context about authentication and success criteria.
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 a single, compact sentence that front-loads the purpose and includes essential safety details without waste.
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 health check, the description fully covers purpose, output, and safety context. The empty input schema and existing output schema (though not detailed) make this 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?
The tool has zero parameters, so the baseline is 4. The description adds nothing about parameters, but none are needed; it correctly focuses on behavior.
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 and resource: 'OliveTin readiness probe (GetReadyz RPC)'. It clearly indicates the tool checks OliveTin health and returns 200/ready, distinguishing it from sibling tools like get_server_info or get_execution_status.
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 clear context for when to use it (readiness check) and adds 'No approval needed — read-only' as a practical usage hint. It does not explicitly contrast with alternatives, so it misses the top score but is still clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Force an immediate refresh of the OliveTin action catalog from GetDashboard. Use this after adding, removing, or editing actions in OliveTin config without waiting for the automatic refresh interval. No approval needed — read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint=true, and the description adds behavioral context by noting 'No approval needed — read-only' and indicating that it forces an immediate refresh. This goes beyond the annotation without contradicting it, though it could be more detailed about side effects or response behavior.
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 concise sentences, each serving a distinct purpose: stating the core action, providing usage timing, and noting safety/read-only nature. Every sentence earns its place with no redundant filler.
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?
With zero parameters and an output schema provided, the description fully covers what an agent needs to know: the tool's function, when to use it, and its non-destructive nature. It is complete for this simple tool.
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 to document beyond the schema. Per the baseline, 0 params earns a 4; the description appropriately focuses on the action rather than parameter semantics.
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 tool's function with a specific verb ('Force an immediate refresh') and identifies the resource ('OliveTin action catalog from GetDashboard'). It distinguishes itself from sibling tools like list_olivetin_actions, making its purpose unambiguous.
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 when-to-use guidance: 'Use this after adding, removing, or editing actions in OliveTin config without waiting for the automatic refresh interval.' This gives clear context but does not mention alternatives or when not to use it, so it falls slightly short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a Chart.js config as PNG via quickchart.io. Returns /tmp path. No approval needed.
| Name | Required | Description | Default |
|---|---|---|---|
| width | No | ||
| config | Yes | ||
| height | No | ||
| background_color | No | white |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already state readOnlyHint=true. The description adds behavioral details beyond that: it returns a /tmp path, uses an external service (quickchart.io), and explicitly states no approval is needed, which are useful for 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 two sentences, front-loaded with the core action, and contains no unnecessary words. Every sentence adds value.
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 rendering tool, the description provides the essential context: purpose, required input type (Chart.js config), the external service, and the output path. It also mentions approval state. Output schema exists, so return values are covered elsewhere.
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. It explains that config is a Chart.js config, giving meaning to the required parameter. Width, height, and background_color are self-explanatory from names and defaults but not described in detail.
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 'Render' and identifies the resource 'Chart.js config' and result 'PNG via quickchart.io', clearly distinguishing it from sibling render_diagram. It also states the output as a return path.
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: it is for rendering Chart.js configs. 'No approval needed' gives a usage guideline about invoking without approval. However, it does not explicitly mention alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a Mermaid diagram spec as PNG via mermaid.ink. Returns /tmp path. No approval needed.
| Name | Required | Description | Default |
|---|---|---|---|
| spec | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, but the description adds valuable behavioral context beyond that: it relies on the external mermaid.ink service, returns a /tmp path, and explicitly states no approval is needed. This is consistent with the annotations and adds operational clarity.
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?
Three short sentences, each carrying essential information: the action and target, the output location, and the approval requirement. There is no wasted wording or redundancy.
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 one-parameter tool with a read-only annotation, the description covers what the tool does, how it operates (via mermaid.ink), where the output goes (/tmp path), and whether approval is needed. No critical information is missing for invoking 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?
While the schema only defines a single 'spec' string with no description, the tool description compensates by identifying it as a 'Mermaid diagram spec'. This gives the parameter meaning beyond the bare schema and is sufficient for a single-parameter tool, though no examples or constraints are provided.
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 ('Render') and resource ('Mermaid diagram spec as PNG via mermaid.ink'), clearly distinguishing it from sibling tools like render_chart. It also states the output location ('/tmp path'), making the tool's purpose unambiguous.
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 clearly implies when to use the tool (when a Mermaid diagram spec needs to be rendered as PNG) and adds an operational note ('No approval needed'). It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restart a previously executed OliveTin action by its execution_tracking_id (RestartAction RPC). Re-runs with the same arguments as the original execution. Requires human approval — this re-triggers a real action on the host.
| Name | Required | Description | Default |
|---|---|---|---|
| execution_tracking_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive behavior (destructiveHint: true). The description adds useful context: approval requirement and that it re-runs with the same arguments as the original execution, which provides caution beyond the raw annotations.
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 concise sentences, front-loaded with the action and includes the essential caveat. No wasted words.
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 core functionality, the approval requirement, and the re-run semantics, which is adequate for a simple one-parameter tool. It omits details like return format, but with an output schema present, those are not strictly necessary.
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 only parameter, execution_tracking_id, is referenced in the description, tying it to the action being restarted. However, it does not explain how to obtain the ID or its format, leaving some ambiguity despite the low schema coverage.
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 verb and resource: 'Restart a previously executed OliveTin action by its execution_tracking_id.' It distinguishes from siblings like start_action_async (new execution) and kill_action by focusing on re-running an existing execution.
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 provides clear context on when to use (for re-running a previously executed action) and the key caveat that human approval is required and it re-triggers a real action. However, it does not explicitly name alternatives or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start an OliveTin action asynchronously (StartAction RPC). Returns an execution_tracking_id immediately without waiting for completion. Use get_execution_status to poll progress, kill_action to cancel. Requires human approval — this triggers a real action on the host.
| Name | Required | Description | Default |
|---|---|---|---|
| action_id | Yes | ||
| arguments | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already indicating destructive intent, the description adds valuable context: 'Requires human approval — this triggers a real action on the host.' It also discloses the async return behavior (execution_tracking_id immediately) without contradicting the annotations, enhancing the agent's understanding of side effects and process.
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?
Three sentences, each earning its place: purpose, async behavior with follow-up tools, and approval requirement. The description is front-loaded with the core action and avoids repetition or fluff.
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 tool with two simple parameters and an output schema, the description covers all essential aspects: what it does, how it behaves, what to do next, and the human approval prerequisite. It is sufficiently complete without needing to explain return values (output schema exists).
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%, placing the burden on the description to explain parameters. The description mentions 'arguments' only in the tool name, not in the description, and fails to explain what arguments are or how they map to the action. The schema shows action_id and arguments but provides no semantic meaning beyond types, leaving a significant gap.
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 tool's purpose: 'Start an OliveTin action asynchronously (StartAction RPC).' It distinguishes from sibling tools by emphasizing async behavior and the immediate return of an execution_tracking_id, which differentiates it from status, cancel, and list 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 explicitly directs users to get_execution_status for polling and kill_action for cancellation, providing clear alternative actions. It also notes the requirement of human approval, implying when this tool is appropriate. However, it does not explicitly state when not to use it (e.g., if synchronous results are needed), so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate an argument value against an OliveTin argument type (ValidateArgumentType RPC). type: unicode | ascii_identifier | url | int | float | bool. No approval needed — read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | ||
| value | Yes | ||
| binding_id | No | ||
| argument_name | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already indicates a read-only operation; the description reinforces this and adds the extra behavioral detail 'No approval needed', which goes beyond the annotation. It also names the RPC and lists allowed input types, but does not mention error behavior or the return format.
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 concise sentences front-load the action and include the essential type list. Every sentence adds value with no redundancy or filler.
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-value details are not needed. However, with four parameters and no schema descriptions, the description leaves 'binding_id' and 'argument_name' underspecified, making it incomplete for a fully informed invocation. It covers the core purpose but not all parameter semantics.
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 compensate. It partially does by enumerating valid values for 'type', but it does not explain the purpose of 'binding_id' or 'argument_name'. The meaning of 'value' is implied but not clarified. This leaves half the parameters underspecified.
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 tool's function: 'Validate an argument value against an OliveTin argument type' (specific verb + resource) and enumerates the supported types. It is unambiguous but does not explicitly differentiate from sibling tools such as start_action_async or list_olivetin_actions.
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 a useful usage trait: 'No approval needed — read-only.' However, it lacks explicit when-to-use guidance or mention of alternatives. The context that this is a validation RPC implies when it would be used, but no exclusions or preferred scenarios are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return information about the current authenticated OliveTin user (WhoAmI RPC). No approval needed — read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces this by stating 'read-only'. It adds valuable context beyond annotations: 'No approval needed' informs the agent that this operation is safe and unauthenticated in terms of approvals, reducing hesitation. The mention of 'WhoAmI RPC' also provides protocol context.
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 a single, compact sentence that conveys all essential information immediately. It is front-loaded with the core action and resource, with safety context appended. Every word earns its place with no redundancy.
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 the tool's simplicity, an empty schema, and an output schema being present, the description is complete. It states the tool's purpose, safety profile, and protocol context. It doesn't need to explain return values because the output schema covers that.
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 input schema is an empty object, so there is nothing to explain. According to the instructions, a baseline of 4 is appropriate for no-parameter tools. The description adds no parameter information because none is needed.
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 tool returns information about the current authenticated OliveTin user, using a specific verb and resource. It uniquely identifies this as a WhoAmI RPC, distinguishing it from all sibling tools which have different purposes.
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 context for when to use this tool is clear: whenever information about the current authenticated user is needed. It doesn't explicitly mention alternatives or exclusions, but the tool is self-contained and no alternative is relevant, so no additional guidance is required.
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.0brave_searchget_action_bindingget_entitiesget_entityget_execution_logsget_execution_statusget_server_infokill_actionlist_olivetin_actionslist_pending_approvalsreadyzreload_actionsrender_chartrender_diagramrestart_actionstart_action_asyncvalidate_argumentwhoamiScored across 18 tools
The core OliveTin tools are mostly distinct, but the inclusion of unrelated tools (brave_search, render_diagram, render_chart) creates confusion about the server's purpose and could lead to misselection. There is also mild overlap between get_execution_logs and get_execution_status, though descriptions help clarify.
Most tools follow a clear verb_noun snake_case pattern (e.g., list_olivetin_actions, get_execution_status, kill_action). Minor exceptions like whoami, readyz, and brave_search deviate from the pattern but are still recognizable and don't cause significant inconsistency.
At 18 tools, the set is on the heavier side. The 15 OliveTin-specific tools are reasonably scoped for the domain, but the three unrelated utility tools pad the count and make the server feel less focused.
The OliveTin surface covers the core lifecycle: listing/getting actions, starting/killing/restarting, status/logs, approvals, entities, validation, user/server info, health, and reload. Minor gaps include lack of entity mutations and synchronous action start, but these are not critical for typical workflows.
The MCP server that vets MCP servers: identity, risk grade and per-tool risk before you install.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
