This server exposes a broad agentic operations surface: it maps and explores infrastructure, answers graph/dependency questions, inspects incidents/logs/state, executes audited actions, and generates evidence-backed views and reports.
Map and fingerprint environments: detect runtimes, clouds, IaC, and telemetry; run full static + live discovery and regenerate artifacts.
Explore the infrastructure graph: query what depends on what, fetch nodes/neighbors, find shortest paths, list services/dependencies/dependents/public entrypoints/runtime workloads.
Gather operational evidence: tail logs, get live component state, and cluster recent error/warning events.
Work with incidents: list incidents (with optional detection pass), and get evidence-backed markdown explanations.
Act safely: list available actions for a component, execute action IDs, and verify their outcomes — all recorded and audited.
Enrich knowledge: manually add nodes/edges with evidence, annotate existing nodes, and see enrichment targets left by scanners.
Generate outputs: create agentic UI views (HTML/MD/JSON) and regenerate INFRA_REPORT.md.
Audit everything: retrieve recent audit entries showing what was observed, generated, executed, and verified.
Integrates with Docker to fingerprint, graph, and monitor containers and services, enabling incident detection and operational actions through the agent.
Integrates with Kubernetes to fingerprint, graph, and monitor clusters, workloads, and resources, enabling incident detection and operational actions through the agent.
Integrates with Terraform to analyze infrastructure-as-code declarations and detect drift against live infrastructure, enabling drift detection and operational actions.
Cirdan is an on-call software repair agent. A production alert fires — Grafana,
Alertmanager, or Slack. Cirdan resolves the affected service and its repo from the
explicit services: registry in cirdan.yaml, reproduces the failure in an isolated
runner (Docker Compose or Kubernetes), has a coding agent fix the code — your own
logged-in Claude Code / Codex CLI, or an API provider — re-verifies the fix against
the pinned reproduction probe and the repo's test suite, and opens a verified pull
request. When policy allows, it merges, deploys, and verifies production recovery,
stopping at manual_required with full evidence when recovery fails.
alert ─▶ resolve service + repo (the services: registry) ─▶ reproduce in an isolated runner
─▶ coding agent fixes the code ─▶ verify (pinned repro probe + sandboxed test suite)
─▶ verified PR (@cirdan review loop; CI checks watched) ─▶ optional merge + deploy
─▶ verify recovery in productionThe job it does: when an alert fires at 3am for a code-shaped failure, a verified fix PR (or a completed deploy plus recovery confirmation) is waiting instead of a page.
Cirdan is deliberately not an infrastructure mapper, a topology explorer, an observability dashboard, a generic agent launcher, or a ChatOps bot. It repairs the services you register — nothing is discovered, and nothing is repaired implicitly.
pipx install "cirdanops[all]" # or uv / pip / npm / brew / curl / docker — see Install
cirdan setup # opens the local, loopback-only setup UIcirdan setup walks one short path and shows a readiness banner that flips to
"Ready to repair" only when this install can actually fix something:
Choose a pathway — Use the CLI (the tools already logged in on this machine) or Use the API (managed credentials + a GitHub App). See Two ways to run.
Connect an alert source — a Grafana webhook (+ HMAC), native Alertmanager intake, or Slack.
Select repair repositories — in Source Code Connection, Cirdan lists the
repos your gh login can push to; pick which ones it may repair. Only selected
repositories are ever repaired.
Prove routing — the Alert routing step synthesizes a sample alert (or takes a real payload you paste) and must show it resolving to a selected repository and routing to a code-repair pipeline.
Start the daemon and post a demo alert:
cirdand serve --http
curl -X POST localhost:8090/v1/ingest/grafana -d @examples/demo/alert.firing.jsonThe runnable demo in examples/demo/ wires this end to end. The
same checklist is available headlessly — cirdan status --checks prints the identical
table and exits 1 until the install is ready. Useful setup flags:
cirdan setup --terminal — the text step flow instead of the UI
cirdan setup --all — run every step without prompting (scripts / CI)
cirdan setup --system — machine-level scope in ~/.cirdan instead of a repo
Related MCP server: NEAT MCP Server
From PyPI (recommended):
uv tool install "cirdanops[all]"
# or
pipx install "cirdanops[all]"
pip install "cirdanops[all]"Without Python — npm / Homebrew / curl:
npx -y @cirdanops/cli serve-mcp # run the MCP server, zero install
npm install -g @cirdanops/cli # or put the `cirdan` command on your PATH
brew install adanb13/tap/cirdan # macOS / Linux (Homebrew)
curl -LsSf https://raw.githubusercontent.com/adanb13/cirdan/main/packaging/install.sh | sh
# Windows: irm https://raw.githubusercontent.com/adanb13/cirdan/main/packaging/install.ps1 | iexThese ship a self-contained binary — no Python 3.11+ required. Supported: macOS (arm64), Linux x64/arm64 (glibc), Windows x64. On Intel Macs, Alpine/musl, or other platforms, use the PyPI install above.
Then set it up in one command (see Quickstart):
cirdan setup # inside a repo
# or, machine-level scope in ~/.cirdan:
cirdan setup --systemBoth open the same guided setup: choose a pathway, connect an alert source + GitHub, select repair repositories, prove routing, and start the always-on daemon.
Targeted installs: cirdanops[mcp], cirdanops[api], cirdanops[slack],
cirdanops[agent], cirdanops[github-app], cirdanops[secrets], or combinations
like cirdanops[api,mcp]. The sandbox runners need no extras — they use the
docker/kubectl CLIs already on your PATH.
Prerequisites by platform (Python 3.11+ and uv or pipx):
# macOS
brew install python@3.12 uv
# Windows
winget install astral-sh.uv
# Ubuntu / Debian
sudo apt install python3.12 python3-pip pipx
# or get uv:
curl -LsSf https://astral.sh/uv/install.sh | shDocker (no Python needed):
# run the always-on repair daemon: alert receiver + isolated repair runner,
# using the host's Docker for sandboxes
docker run -d \
-v "$PWD":/workspace:ro \
-v /var/run/docker.sock:/var/run/docker.sock \
-p 127.0.0.1:8090:8090 \
ghcr.io/adanb13/cirdan(or docker compose up with the provided docker-compose.yml)
From source (latest unreleased):
pip install "cirdanops[all] @ git+https://github.com/adanb13/cirdan.git"Two commands are installed:
Command | What it is |
| Human/agent CLI |
| Long-running Always ON daemon |
Contributors work from a clone with an editable virtualenv, so changes to the
working tree take effect immediately — no reinstall between edits. make install
creates .venv and installs the package (distribution name cirdanops) editable with
the [all,dev] extras — every runtime feature plus the test toolchain:
git clone https://github.com/adanb13/cirdan.git
cd cirdan
make install # ≈ python3 -m venv .venv && .venv/bin/pip install -e ".[all,dev]"
make test # .venv/bin/python -m pytest tests/ -qRequires Python 3.11+. The manual two-line equivalent works on a standard Python;
make install additionally handles the pip-less-venv case (it falls back to
python3 -m venv --without-pip and bootstraps pip into the venv).
The editable install puts both console scripts in .venv/bin, running working-tree
code with no rebuild:
.venv/bin/cirdan setup # or: .venv/bin/python -m cirdan.cli.main setup
.venv/bin/cirdand serve --http
.venv/bin/python -m pytest tests/test_slack_events.py -q # a single test moduleCommon Make targets (make help lists them all):
target | what it does |
| create |
| run the full pytest suite |
| build the sdist + wheel into |
| reset a project's onboarding so |
| build and drive the runnable stack in |
On a headless box with no OS keyring, storing credentials during
cirdan setupneeds a master key in the environment first:export CIRDAN_MASTER_KEY=$(.venv/bin/python -c 'import os,base64;print(base64.b64encode(os.urandom(32)).decode())').
The first setup screen picks a deployment posture (deployment_mode: in
cirdan.yaml), which gates everything after it:
Use the CLI (cli, the default) — Cirdan runs with the tools already logged in on
this machine. GitHub writes go through your gh auth login; the coding agent is a
detected, logged-in Claude Code or Codex CLI, spawned headless inside the isolated
repair workspace; the sandbox runner is your local Docker (or kubectl). The happy path
needs no stored keys and no GitHub App — an env-var API key and a GitHub App
remain available behind explicitly labeled "Advanced" toggles.
Use the API (api) — headless and managed, for shared/enterprise deployments.
Provider API keys are stored encrypted (cirdan secret; AES-256-GCM), GitHub writes
go through a GitHub App (guided manifest onboarding) with short-lived per-repo
installation tokens, and the enterprise security profile is derived automatically:
inherited gh auth and host-spawned CLI agents are refused at config load.
Both pathways end at the same readiness contract — the setup UI banner and
cirdan status --checks render the same table: repair repositories selected (each with a
resolvable repo) · an alert source connected · a routing proof (a sample or live
alert demonstrably resolved to a selected repository and routed to a code pipeline) ·
remediation.mode ∈ {develop, deliver} · a live-probed coding agent · a verified
GitHub write path including access to each selected repo · git on PATH · a
working sandbox runner · the daemon running. Every red row shows the exact fix
command or the setup step that resolves it.
Legacy configs load forever: deployment_mode: single-user reads as cli,
business as api, and the file text migrates on the next setup save.
cirdan setup writes cirdan.yaml for you; everything is also hand-editable — see
cirdan.yaml.example. The heart of the file is the
services: registry: the explicit list of services Cirdan may repair, how alerts
resolve to them, and where their code lives.
services:
- name: checkout-api # canonical id (lowercase, node-id-safe)
repo: acme/checkout # "org/name" — the PR / repair target
aliases: [checkout, checkout-svc] # extra alert-label names for this service
match_labels: {team: payments} # optional exact label matchers (first match wins)
deploy: # how it runs in prod + how the runner rebuilds it
kind: compose # compose | k8s | helm
compose_service: checkout-api # defaults to the entry name
compose_files: [docker-compose.yml]
deploy_workflow: deploy.yml # per-service GitHub Actions deploy (optional)
telemetry_service: checkout # Loki/PromQL service label; defaults to name
- name: payments-api
repo: acme/payments
source_root: ~/src/payments # local checkout (cli pathway only)
deploy:
kind: k8s
namespace: prod
workload: payments-api # kubernetes_kind defaults to DeploymentAlerts resolve to a service by an explicit cirdan_node label, then match_labels,
then a ladder of common labels (service, service_name, app, job,
deployment, statefulset, pod, container, the host of instance,
annotations.service, alertname) matched against names + aliases. There is no
implicit default: an alert that matches nothing opens a triage incident and never
auto-repairs "the only registered repo".
Routing policy. Every alert source flows through one first-match-wins policy:
routing_policy:
rules:
- when: {service: checkout-api, severity: [high, critical]}
pipeline: full_remediation # may merge/deploy — only under mode: deliver + the auto_* gates
- when: {source: slack}
pipeline: triage_onlyWith no matching rule, an alert that resolves to a registered service with a
resolvable repo defaults to reproduce_and_pr_only at qualifying severity
(responder.severities, default high/critical); everything else fails safe to
triage_only. Pipelines, by decreasing depth: full_remediation ·
reproduce_and_pr_only · lightweight_pr_only · triage_only.
Safety gates (under source_hosts.github and remediation):
gate | default | what it does |
|
| a PR opens only when the failure was reproduced (baseline probe failed) AND the fix verified (post-fix probe passed) |
|
| additionally require a passing sandboxed repo-test run before any PR |
|
| enable GitHub-native auto-merge on Cirdan PRs — branch protection and reviewers still gate the real merge; Cirdan never force-merges |
|
| master switch for delivery: deploy the merged fix and re-verify in production |
|
| block deploy dispatch until the merge commit's CI checks are green (block-only: it can stop a deploy, never start one) |
|
| ceiling on what any pipeline may do; |
A failed deploy or failed production verification stops the delivery at
manual_required, with the failure evidence notified and audited — Cirdan stops
at manual intervention (automatic rollback is deliberately deferred).
cirdan setup # guided setup: loopback UI (default) or --terminal
cirdan install --project # scripted variant: hook agents, register MCP, arm responder, start daemon
cirdan incidents # detection pass + list incidents
cirdan explain <incident-id> # evidence-backed explanation
cirdan respond <incident-id> # write the incident brief + invoke the responder once under a mode
cirdan remediate <incident-id> # durable fix: isolated workspace → reproduce → fix → verify → PR
cirdan deliver <incident-id> # manually drive an in-flight delivery (merge → deploy → prod-verify)
cirdan watch # foreground event + incident stream
cirdan status [--checks] # daemon status; --checks runs the full readiness checklist
cirdan stop # stop the daemon for this scope
cirdan secret set|get|list|delete # encrypted credential store (provider keys, App key)
cirdan slack-app # emit the importable Slack app manifest for the configured intake
cirdan preview-intake # dry-parse a sample payload; --source/--service runs the routing proof
cirdan serve-mcp # MCP server (stdio; --transport streamable-http)cirdand serve # ingest alerts, detect incidents, repair, deliver — forever
cirdand serve --http # + the HTTP API (alert ingestion endpoints)
cirdand serve --http --mcp # + MCP mounted at /mcpThe daemon runs supervised loops — access refresh, alert ingestion + incident
detection, delivery, PR-checks watching, @cirdan comment handling, and the Slack
inbox (plus the Socket Mode client and webhook wakers, as configured). A crashing
loop logs and restarts; it never takes the daemon down.
One instance per scope: a second cirdand serve (or cirdan watch) against the same
scope is refused with the running pid. cirdan status / cirdan stop (also available
on cirdand) inspect and shut it down.
Cirdan is also a tool surface for your coding agents: the same engine behind the CLI
is exposed over MCP with exactly six read/evidence tools — list_incidents,
explain_incident, get_recent_errors, get_logs, get_state, and get_audit.
get_logs and get_state take a registered service name (or alias) from
services: and resolve the live container/pod themselves. Everything returned is
redacted.
cirdan install --project # full guided setup (recommended)
cirdan setup # re-run the guided setup anytime
cirdan install --platform claude # .claude/skills/cirdan/SKILL.md + CLAUDE.md + .mcp.json
cirdan install --platform codex # AGENTS.md + .codex/cirdan.md
cirdan install --platform cursor # .cursor/rules/cirdan.mdc + .cursor/mcp.json
cirdan install --platform gemini # GEMINI.md
cirdan install --platform vscode # .github/copilot-instructions.md + .vscode/mcp.json
cirdan install --platform windsurf # .windsurf/rules/cirdan.md (MCP: global config)
cirdan install --platform roo # .roo/rules/cirdan.md + .roo/mcp.json
cirdan install --platform cline # .clinerules/cirdan.md (MCP: editor UI)
cirdan install --platform opencode # AGENTS.md + opencode.json
cirdan install --platform goose # .goosehints (MCP: global config)
cirdan install --platform generic # .agents/skills/cirdan/SKILL.md + AGENTS.mdcirdan install --project is a guided setup that leaves Cirdan running the repair
loop, not just documented:
detects the agents on your machine (claude/codex/cursor/gemini/vscode/windsurf/opencode/goose config or CLIs) and writes instruction files for exactly those (plus generic AGENTS.md)
registers the MCP server in .mcp.json
arms the incident responder so daemon alerts route to your agent
starts the always-on daemon (detached; cirdand status / cirdand stop)
Steps 3–4 are prompted (default yes) or driven by flags for scripts:
--responder/--no-responder, --daemon/--no-daemon, --all-platforms. Re-run any of
it later with cirdan setup, which shows each step's current state and only proposes
what's missing. Installs are idempotent and never touch content outside Cirdan's own
marker block.
Supported agents. First-class auto-registration (native instruction file + MCP where the agent supports a writable config) covers Claude Code, Codex, Cursor, Gemini, VS Code (+ GitHub Copilot), Windsurf, Roo Code, Cline, opencode, and Goose. Any other agent works through the generic AGENTS.md + .agents/skills/cirdan/SKILL.md. Auto-detection finds claude/codex/cursor/gemini/vscode/windsurf/opencode/goose; pass --platform roo or --platform cline explicitly (they're VS Code extensions with no CLI to detect, and Cline keeps MCP config in editor storage, so add that one through its UI).
For any MCP client not listed, register Cirdan by hand — no Python required:
// npx form — zero install
{ "command": "npx", "args": ["-y", "@cirdanops/cli", "serve-mcp"] }
// or, if `cirdan` is already on PATH (pip / npm -g / brew / curl install):
{ "command": "cirdan", "args": ["serve-mcp"] }With the [api] extra, cirdand serve --http exposes /health, /incidents,
/incidents/{id}, /incidents/{id}/explain, /audit, the alert intake under
/v1/ingest/{grafana|alertmanager|…} (plus /v1/ingest/slack/events and a
signature-verified /v1/ingest/github webhook waker), /v1/slack/interactions, a
minimal OTLP/HTTP JSON receiver at /v1/logs, and the setup UI + API under /setup.
Add --mcp to mount the MCP server at /mcp. State-changing routes are guarded —
see SECURITY.md.
Nothing happens automatically — PyPI is pull-only, so an installed version keeps working as-is until you upgrade. New installs always get the latest release. Upgrading is one command, matching however you installed:
Installed via | Upgrade command |
|
|
|
|
|
|
npm ( |
|
Homebrew |
|
curl installer | re-run the install script (it fetches the latest) |
Docker |
|
Two operational notes: existing cirdan-out/ artifacts and the SQLite store are compatible across releases so far (a schema-version key + migration will land before 1.0). And the CLI prints a single dim line on stderr when a newer release exists (checked at most once a day, interactive terminals only) — silence it with CIRDAN_NO_UPDATE_CHECK=1.
Cirdan committed to a single product: the repair workflow. The infrastructure-mapping surface — the graph/exploration commands, runtime profiles, and their artifacts — was removed. Removed commands and what replaces them:
Removed command | What replaces it |
| the explicit |
|
|
|
|
Old configs keep loading: adapters:, enrich:, and profile: keys are accepted and
ignored (profile warns once — Cirdan always runs the repair workflow), and
deployment_mode: single-user/business normalize to cli/api. The [map] and
[terraform] extras are gone from packaging. Old artifacts (infra.graph.json,
INFRA_REPORT.md, infra.html, fingerprint.json, …) simply stop being written —
Cirdan never deletes your files.
Cirdan mirrors the access of the process it runs in and never escalates; everything it writes is redacted and audited. The two postures draw different trust boundaries: "Use the CLI" runs your own logged-in tools with your own permissions, while "Use the API" enforces the enterprise profile (GitHub App + stored keys, no host CLIs). Details — including network behavior and why PRs can only ever target the configured repo — in SECURITY.md.
Apache-2.0
Attach evidence or attributes to an existing node without changing its confidence.
| Name | Required | Description | Default |
|---|---|---|---|
| node_ref | Yes | ||
| evidence | No | ||
| attrs | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It states that confidence is unchanged, which is helpful, but does not mention side effects, overwrite behavior, or permissions required.
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 sentence that is concise, front-loaded with the verb, and contains no extraneous words. Every word 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 complexity (anyOf, defaults, required params) and no schema descriptions, the description is somewhat complete but lacks details on how to use evidence and attrs. The output schema exists, so return values are covered.
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%, yet the description only vaguely references 'evidence or attributes' without explaining the format or usage of the three parameters (node_ref, evidence, attrs). The description adds minimal value over the schema itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (attach), the resource (existing node), and the constraint (without changing confidence). It distinguishes from sibling tools like upsert_node which modify node properties.
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 adding evidence or attributes to an existing node, but lacks explicit guidance on when to use this tool versus alternatives (e.g., upsert_node, execute_action) or prerequisites like node existence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute an action id from list_available_actions. Recorded, redacted, audited.
| Name | Required | Description | Default |
|---|---|---|---|
| action_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose behavioral traits. It mentions 'Recorded, redacted, audited', which indicates logging and redaction, but does not detail side effects, permissions, or what redaction entails. This is insufficient for full transparency.
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 sentence plus three words, very concise. It avoids unnecessary fluff and is front-loaded with the core purpose. However, it could be slightly more structured without losing brevity.
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 low complexity (one parameter, output schema exists), the description suffices. It references the source tool and notes auditing. With output schema present, return value explanation is not needed. Complete for its complexity.
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 0% description coverage for the single parameter 'action_id'. The description adds meaning by linking it to list_available_actions, clarifying the source and expected format. This compensates for the lack of schema descriptions.
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 'Execute' and resource 'action id', and references the sibling tool 'list_available_actions', which distinguishes it from other tools. It specifies the action comes from that list, giving clear 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 usage after calling list_available_actions, but does not explicitly state when to use this tool over alternatives like verify_action. No when-not or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Evidence-backed markdown explanation of an incident.
| Name | Required | Description | Default |
|---|---|---|---|
| incident_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'evidence-backed markdown explanation' without disclosing any behavioral traits such as side effects, idempotency, authorization needs, or performance characteristics. The lack of detail is a significant gap.
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 extremely concise (one short sentence), which is good for conciseness and front-loading. However, it is underspecified for the information needed, leading to a borderline score.
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 has only one parameter and an output schema exists, the description still lacks completeness. It does not explain what 'evidence-backed' means, what the input incident_id represents, or what format the output takes beyond 'markdown'. This is insufficient for effective tool selection.
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 'incident_id' has no description in the schema (0% coverage) and the description adds no meaning about its format, source, or constraints. For a one-parameter tool, the description should compensate by explaining the parameter's role, but it does not.
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 indicates the tool provides an explanation of an incident in markdown format, with evidence. The verb 'explain' and resource 'incident' are specific, but does not differentiate from similar siblings like 'get_node' or 'generate_report', which could also provide incident details.
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?
No guidance on when to use this tool versus alternatives. Lacks context for appropriate use cases or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detect runtimes, clouds, IaC, and telemetry with confidence and evidence.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It does not state whether the tool is read-only, destructive, requires authentication, or has rate limits. The mention of 'confidence and evidence' hints at output quality but lacks specificity.
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 sentence of 11 words, very concise. However, it might be too terse for a tool with no parameters and many siblings; additional context could improve usability.
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 has no parameters and an output schema exists (assumed helpful), the description is sufficient but not thorough. It does not explain how this differs from related sibling tools like 'list_runtime_workloads' or 'map_infrastructure'.
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?
There are zero parameters, so the schema coverage is 100% by default. The description adds meaning by specifying what the tool detects (runtimes, clouds, IaC, telemetry), which compensates for the absence of parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool detects runtimes, clouds, IaC, and telemetry, using the verb 'detect'. However, it does not explicitly differentiate from sibling tools like 'explain_incident' or 'get_logs', which might also perform detection-like functions.
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 no explicit guidance on when to use this tool versus alternatives. No context about prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Regenerate INFRA_REPORT.md and return its contents.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden but only says 'regenerate', implying a write operation. It does not clarify whether the action is destructive, any permission requirements, or side effects beyond generating the file.
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 sentence that is front-loaded with the verb and resource. No wasted words; every part is necessary.
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 has no parameters and an output schema exists, the description covers the core purpose. However, it could benefit from more detail on what 'regenerate' entails (e.g., full recompute, any triggers). Still, it is reasonably complete for a simple action.
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?
No parameters exist, so schema coverage is 100%. The description adds value by specifying the exact file name and that contents are returned, which is beyond the empty 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 regenerates a specific file (INFRA_REPORT.md) and returns its contents. The verb 'Regenerate' and specific resource set it apart from sibling tools that deal with nodes, actions, incidents, etc.
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?
No guidance on when to use this tool versus alternatives or when not to use it. The description only states the action without any context on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate an Agentic UI view ('show me …') and save html/md/json artifacts.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses artifact saving behavior beyond annotations (none provided). However, lacks detail on auth requirements, rate limits, or whether it modifies state, which is important for a generative tool.
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?
Single sentence of 12 words, front-loaded with main action. No redundancy or irrelevant detail.
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?
Output schema exists but description doesn't mention return format. Lacks guidance on invalid requests or crafting effective 'show me' phrases. Adequate for a simple tool but leaves gaps.
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 0% schema coverage, description adds minimal meaning via 'show me …' hint. Does not describe format, constraints, or examples for the 'request' string, leaving agents underinformed.
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?
Clearly states verb 'Generate' and resource 'Agentic UI view', with specific artifact types (html/md/json). Distinguishes from sibling 'generate_report' by focusing on UI views rather than reports.
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 no explicit when-to-use vs alternatives like 'get_node' or 'generate_report'. Only implicit guidance via 'show me …' phrase, leaving selection ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What the current agent/session can access (capability mirror, not permissions).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. The phrase 'capability mirror, not permissions' effectively discloses that the tool reflects capabilities rather than actual permissions, a key behavioral trait.
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?
Single sentence, zero waste, front-loaded with key information. Every word 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 zero parameters and an output schema exists, the description is fully complete. It explains the core distinction, and no further details are 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?
With zero parameters, baseline is 4. The description adds meaningful context about the output nature, fulfilling the requirement.
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 what the current agent/session can access, with a specific qualifier 'capability mirror, not permissions'. This distinguishes it from permission-checking tools and provides a precise verb-noun structure.
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 capability introspection, and the note about 'not permissions' helps guide when to use this vs. permission-related tools. However, it lacks explicit when-to-use/not-use alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent audit entries: what Cirdan observed, generated, executed, verified.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lists the types of audit entries but does not disclose behavioral traits such as read-only nature, authentication requirements, rate limits, or ordering. With no annotations, the description fails to adequately inform the agent about tool 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 concise (one sentence) and front-loaded with the main purpose. However, it could include parameter details without adding verbosity.
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 (one optional parameter, output schema exists), the description is insufficient. It lacks usage guidance and parameter semantics, leaving gaps for the agent.
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 input schema has one parameter (limit), but the description provides no information about it. Schema description coverage is 0%, so the description does not help the agent understand the parameter's purpose or usage.
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 'Recent audit entries' and specifies the types of entries (observed, generated, executed, verified), clearly indicating the tool retrieves audit records. However, it does not differentiate from sibling tools like get_logs or get_recent_errors.
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?
No guidance is provided on when to use this tool versus alternatives. There are no instructions on context, prerequisites, or cases where this tool should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What the deterministic scanners left unconnected: docs to read, isolated nodes, unlinked IaC, uncertain claims. Contribute findings via upsert_edge.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It fails to disclose behavioral traits such as whether the tool is read-only, what the output contains beyond vague categories, or any constraints like rate limits or authentication requirements. The description is insufficient for an agent to understand side effects or limitations.
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 short (two sentences), but the first sentence is a fragment that is not immediately clear. It is somewhat concise but sacrifices clarity. The key information is front-loaded, but the phrasing is ambiguous.
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?
While the tool has zero parameters and an output schema exists, the description does not explain what specific items are returned or how to interpret them. Given the number of sibling tools, the description should provide more context on the nature of 'enrichment targets' and the expected output format.
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?
There are zero parameters, and schema description coverage is 100% (vacuously). The description does not need to add parameter information. Baseline for 0 params is 4.
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 implies the tool returns unconnected items from deterministic scanners (docs, isolated nodes, etc.), but it does not explicitly state that the tool lists or retrieves these items. The verb 'get' is in the name, but the description does not clearly articulate the action. It is not a tautology, but the purpose is vague.
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 mentions 'Contribute findings via upsert_edge', which suggests a follow-up action, but does not provide any guidance on when to use this tool versus sibling tools like 'get_node' or 'list_incidents'. There is no explicit when-to-use or when-not-to-use information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tail logs for a component through the owning live adapter.
| Name | Required | Description | Default |
|---|---|---|---|
| node_ref | Yes | ||
| lines | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It mentions 'tail' implying streaming or following, but does not explain if it blocks, how it handles connections, or any side effects. Missing details like whether it polls or streams.
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 sentence, concise but at the expense of necessary detail. While not overly verbose, it could be more informative without adding much length.
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 has 2 parameters and an output schema, the description should cover key behaviors and parameter meanings. It is incomplete, omitting how to use the parameters and what the output contains. No mention of real-time behavior.
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 fails to mention the parameters: 'node_ref' (required, likely the component ID) and 'lines' (default 100). The phrase 'for a component through the owning live adapter' hints at node_ref but lacks 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 action 'Tail logs' and the resource 'for a component through the owning live adapter', which is a specific verb+resource combination. However, it does not distinguish from siblings like 'get_recent_errors' or 'get_state' that might also relate to log-like data.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., get_recent_errors, get_state). The description lacks any context about appropriate usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Neighborhood subgraph around a node.
| Name | Required | Description | Default |
|---|---|---|---|
| node_ref | Yes | ||
| depth | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fails to disclose behavioral traits such as read-only nature, permissions, or side effects. It only states the output type without any safety or cost implications.
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 very concise (one sentence) and front-loaded with the primary purpose. However, it is too minimal and lacks structure that would make it more informative without significant verbosity.
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 existence of an output schema, the description does not need to detail return values, but it still lacks context about typical use cases, edge cases (e.g., depth limits), or integration with sibling tools. Incomplete for a tool with two parameters.
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 description does not explain the parameters 'node_ref' or 'depth'. Even though the schema has defaults and types, no semantic context is given, leaving agents to infer meaning from names alone. Schema coverage is 0%.
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 'Neighborhood subgraph around a node' clearly states the tool returns a subgraph of neighbors. It distinguishes from siblings like 'get_node' (single node) and 'shortest_path' (path). However, it could be more specific about including edges and nodes.
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?
No guidance is given on when to use this tool versus alternatives like 'list_dependencies' or 'query_infra_graph'. The description only states what it does, not when to prefer it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one node (by id or fuzzy name) with evidence, attributes, and edges.
| Name | Required | Description | Default |
|---|---|---|---|
| node_ref | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description mentions return content but does not disclose read-only nature, error behavior, authorization needs, or rate limits. Minimal behavioral context beyond the core action.
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?
Single sentence, 12 words, front-loaded with verb and resource. No wasted words, efficiently conveys essential information.
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?
Output schema exists, so return value details not needed. Description covers what the tool does and returns. Lacks some usage context and behavioral details, but for a simple fetch tool, fairly 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?
Parameter 'node_ref' has 0% schema description coverage. Description adds meaning: 'node id or fuzzy name', but lacks format, examples, or constraints. Some value added beyond schema, but not fully detailed.
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?
Description has specific verb 'Fetch', resource 'one node', method 'by id or fuzzy name', and includes what is returned ('with evidence, attributes, and edges'). Clearly distinguishes from sibling tools like get_neighbors.
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?
No explicit when-to-use or when-not-to-use guidance. Implies use for fetching a single node, but does not contrast with siblings like get_neighbors or get_state.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent error/warning events, clustered by message template.
| Name | Required | Description | Default |
|---|---|---|---|
| window_minutes | No | ||
| service | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden but only states that events are 'clustered'. It does not disclose behavioral traits such as read-only nature, rate limits, permissions required, or how the clustering works.
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 sentence, front-loaded and efficient. However, it lacks necessary detail, making it under-specified rather than concise.
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 (not provided) which may explain return structure, but the description omits parameter semantics and usage context, leaving the tool incomplete for an agent that needs to set parameters 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 input schema has two parameters (window_minutes, service) with no descriptions. The tool description does not explain their purpose, defaults, or allowed values, leaving the agent without guidance despite 0% 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 tool returns recent error/warning events and specifies they are clustered by message template. This gives a specific verb and resource, but does not explicitly distinguish it from similar tools like get_logs.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., get_logs) or when not to use it. The usage context must be inferred from the tool name and general domain knowledge.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Live state of a component through the owning adapter.
| Name | Required | Description | Default |
|---|---|---|---|
| node_ref | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description does not disclose behavioral traits such as read-only status, authentication needs, or side effects. The phrase 'live state' is undefined.
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 extremely short but at the expense of clarity. It is under-specified rather than concise, providing insufficient information for correct tool invocation.
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 presence of an output schema and many sibling tools, the description omits essential details like return format, parameter constraints, and disambiguation from similar tools. It fails to provide a complete picture.
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%, yet the description adds minimal value for the sole parameter 'node_ref'. The mention of 'through the owning adapter' hints at context but does not clarify the parameter's meaning or usage.
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 'Live state of a component through the owning adapter' lacks a clear action verb. It vaguely implies retrieving state but does not specify what 'live state' means or how it differs from siblings like get_node or get_logs.
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?
No guidance is provided on when to use this tool versus alternatives. With many sibling tools like get_node, get_logs, and get_access_context, the absence of usage context makes selection difficult.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Actions currently possible against a component with this session's access.
| Name | Required | Description | Default |
|---|---|---|---|
| node_ref | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry the full burden. It only mentions 'actions currently possible' and 'session's access', but does not disclose behavioral traits such as whether the action list is mutable, how session access is determined, or if the tool performs any side effects.
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, which is concise. However, it is too brief to adequately inform the agent, lacking critical details about usage and parameter.
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 26 sibling tools in a complex domain, the description provides insufficient context. Although an output schema exists, the description does not explain what 'available actions' means or how it relates to session access, leaving the agent underinformed.
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 sole parameter 'node_ref' is required but not described in the description. Schema description coverage is 0%, so the agent gets no help understanding what 'node_ref' expects or how to format it beyond the parameter name.
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 identifies the tool as listing actions possible for a component given session access. However, it does not differentiate from sibling tools like 'execute_action' or 'verify_action', which reduces clarity.
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?
No guidance is provided on when to use this tool versus alternatives. Without any context on when to choose 'list_available_actions' over siblings, the agent lacks decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What a component depends on (transitive).
| Name | Required | Description | Default |
|---|---|---|---|
| node_ref | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The word 'transitive' is a useful behavioral disclosure, but with no annotations, the description should also state that the tool is read-only, what the output structure is, and any performance considerations. It does not.
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 extremely short (5 words) but under-informative. It is not a full sentence and reads more like a label. Conciseness should not come at the cost of completeness.
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 one required parameter, no annotations, and an output schema, the description fails to explain what the output is, how to interpret transitive dependencies, or what constitutes a component. It is grossly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning to the 'node_ref' parameter. The parameter's purpose and format are left entirely to inference.
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 'What a component depends on (transitive)' clarifies that it lists dependencies transitively, but 'component' is vague and the verb is implied from the tool name. It distinguishes from sibling 'list_dependents' only by being the inverse, but doesn't explicitly state this.
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?
No guidance on when to use this tool versus alternatives like 'list_dependents' or other tools. The description does not mention prerequisites, context, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What depends on a component (transitive blast radius).
| Name | Required | Description | Default |
|---|---|---|---|
| node_ref | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly mentions 'transitive blast radius', indicating recursive dependency traversal. However, without annotations, it fails to disclose potential performance implications, required permissions, or whether the output is a list of node references.
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 wastes no space, though it could be expanded slightly without losing conciseness.
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?
While the description covers basic purpose, it lacks usage context. Given the presence of an output schema, the description does not need to detail return values, but it should provide more guidance on when to use this tool, especially given the large sibling list.
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 0% schema description coverage, the description adds no meaning beyond the schema's 'Node Ref'. The parameter 'node_ref' is not elaborated, forcing agents to infer its meaning from the tool name.
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 what depends on a component, specifically highlighting transitive dependencies ('blast radius'). This distinguishes it from sibling tools like 'list_dependencies', which likely show inverse relations.
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?
No guidance on when to use this tool versus alternatives like 'list_dependencies' or 'get_neighbors'. The description implies transitive behavior but does not clarify scope limitations or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open (and optionally resolved) incidents. Runs a detection pass by default.
| Name | Required | Description | Default |
|---|---|---|---|
| include_resolved | No | ||
| detect_first | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that a detection pass runs by default, but does not clarify if this is a read-only operation or has side effects (e.g., modifying detection state). No information about permissions, rate limits, or whether resolved incidents are included by default is given.
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, immediately stating purpose and key behavior. 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?
The output schema exists, so return values are covered. However, the description omits details like default filtering (open vs. all), ordering, pagination, or what incident fields are returned. For a simple tool, this may be adequate, but more context would improve completeness.
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 implicitly describes 'detect_first' by stating it runs a detection pass by default, and 'include_resolved' by referencing optional resolved incidents. However, it does not explicitly name or explain the parameters, leaving some ambiguity about how they map to 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 it lists open and optionally resolved incidents, with a specific verb and resource. It distinguishes from sibling tools since no other tool explicitly lists incidents. However, the phrasing 'Open (and optionally resolved) incidents' is slightly ambiguous about whether 'open' is part of the tool name or a filter.
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 no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The mention of a default detection pass hints at configuration but does not compare to sibling tools like 'get_node' or 'explain_incident'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everything reachable from outside, with the reasons.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description lacks any behavioral details such as read-only nature, side effects, authentication needs, or rate limits. The tool's behavior is completely opaque.
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 extremely short (one sentence) but lacks substantive information. While concise, it fails to convey the tool's purpose, making it under-specified rather than efficiently compact.
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?
Despite having an output schema and zero parameters, the description does not clarify what 'entrypoints' are, the scope of 'outside', or the format of output. It is insufficient for an agent to use 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?
No parameters exist, and schema description coverage is 100%, so the description does not need to explain parameters. Baseline for zero parameters is 4.
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 'Everything reachable from outside, with the reasons' is vague and does not clearly state the verb (e.g., list) or the specific resource (e.g., network entrypoints, service endpoints). It fails to distinguish from sibling tools like list_services or list_dependencies.
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?
No guidance on when to use this tool versus siblings. There is no mention of context, prerequisites, or alternatives among the 25 sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current workloads (services, containers, pods, units) with live state.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions 'live state' but does not disclose read-only nature, pagination, performance, or any side effects. The description is too minimal to adequately inform behavioral expectations.
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, concise sentence that front-loads the core purpose. Every word is useful and no extraneous information is present.
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 has no parameters and an output schema exists, the description is reasonably complete. It mentions 'live state' and lists example workload types. While more context on scope or filtering could enhance it, it is adequate for a simple list 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?
There are no parameters in the schema, and schema coverage is 100%. With zero params, the baseline is 4. The description does not need to add parameter details, so it scores well here.
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 specifies the verb (list, implied by name) and resource (runtime workloads) with examples of types (services, containers, pods, units). It distinguishes from siblings like 'list_services' by focusing on runtime state and including broader workload types.
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 retrieving live state of workloads but provides no explicit guidance on when to use this tool versus alternatives like 'list_services' or 'get_node'. No when-not or conditionals are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
All logical services with state and origin.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only mentions returned content (state and origin) but discloses no behavioral traits such as idempotency, auth needs, or performance characteristics.
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, clear phrase with no wasted words. It is appropriately sized for a simple, parameterless tool.
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 output schema exists, so return values are documented. However, the description does not explain what 'logical services' are or how to interpret state and origin, which may leave an agent with insufficient context.
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?
There are no parameters (schema coverage 100%). The description adds context by specifying 'logical services' and 'state and origin,' which provides meaning beyond the empty 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 states 'All logical services with state and origin,' which clearly identifies the verb (list) and resource (logical services) and distinguishes from sibling tools like list_runtime_workloads or list_incidents.
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?
No explicit guidance on when to use this tool versus alternatives (e.g., list_runtime_workloads). The description does not mention context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run full discovery (static + live) and regenerate all cirdan-out artifacts.
| Name | Required | Description | Default |
|---|---|---|---|
| live | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behaviors. It mentions 'regenerate all artifacts' but does not explain if this is destructive, what happens to existing artifacts, or any side effects like data overwrite.
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 very concise at one sentence. While efficient, it could include more detail without being verbose, so it is not perfect.
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 potentially performs a heavy operation (full discovery and regeneration) with no annotations, the description lacks important context like scope, duration, or whether it can be run concurrently. The presence of an output schema helps but not enough.
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 'live' has no description in the schema (0% coverage) and is not mentioned in the tool description. The agent has no clue what this boolean does.
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 runs 'full discovery (static + live)' and regenerates artifacts, specifying the action and output. However, 'cirdan-out artifacts' is domain jargon that may reduce clarity for agents unfamiliar with the project.
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?
No guidance on when to use this tool versus alternatives like 'fingerprint_system' or 'query_infra_graph'. No prerequisites or context for when the tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask the graph a question, e.g. 'what depends on postgres?' or 'what broke?'.
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states 'Ask the graph a question' without disclosing behavioral traits such as read-only nature, side effects, or required permissions. The output format is not hinted, even though an output schema exists.
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 sentence with examples, containing zero wasted words and placing the core action upfront. It is appropriately concise.
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 complexity (many sibling tools, one parameter, output schema exists), the description is insufficient. It fails to explain the output format, how it differs from similar tools, or provide usage context beyond simple examples.
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 'question' has 0% schema description coverage, but the description adds meaning by specifying it is a natural language question and provides examples. However, it does not clarify syntax, length limits, or how to structure complex queries.
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 'Ask the graph a question' with clear verb 'ask' and resource 'the graph', and provides two examples. However, it does not distinguish this tool from sibling tools like list_dependencies or list_dependents, which may have overlapping functionality.
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 examples but no explicit guidance on when to use this tool versus its siblings. There is no mention of when not to use it or what alternative tools exist for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Shortest path between two components.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ||
| target | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It merely states 'shortest path' without mentioning algorithm specifics, handling of missing paths, or side effects. Important details are omitted.
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, concise sentence that efficiently conveys the core function. It is front-loaded and avoids unnecessary detail, though it could benefit from minor elaboration without losing brevity.
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 complexity of graph pathfinding and the presence of sibling tools, the description is incomplete. It does not specify what 'components' are, how the graph is defined, or any output schema details, making it insufficient for confident use.
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 clarify parameter semantics. It does not explain what 'source' and 'target' represent (e.g., component IDs, labels) or their expected format, leaving the agent uncertain.
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 that the tool finds the shortest path between two components, using a specific verb and resource. It is distinct from siblings like 'get_neighbors' or 'query_infra_graph', but could be more explicit about the graph context to further differentiate.
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?
No guidance is provided on when to use this tool over alternatives such as 'get_neighbors' or 'query_infra_graph'. The description lacks context for appropriate usage scenarios or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Contribute a relationship between existing nodes (ids or names). Evidence required.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ||
| target | Yes | ||
| relation | Yes | ||
| evidence | Yes | ||
| attrs | No | ||
| ambiguous | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It uses the vague 'Contribute' instead of clarifying mutation or idempotency. Does not mention permissions, side effects, or what happens if evidence is insufficient. Minimal behavioral 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 short sentence, which is concise but lacks structure. It front-loads the core action but omits details that might be in a more structured description. It is not overly verbose, but the brevity sacrifices clarity.
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 complexity (6 parameters, 4 required, no enums, output schema exists), the description is incomplete. It does not reference the output schema, explain the upsert semantics, or provide enough context to use the tool correctly alongside siblings.
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%. The description adds that source/target can be ids or names and that evidence is required, but fails to explain 'relation', 'attrs', or 'ambiguous'. This is insufficient given 6 parameters, leaving agents to guess their meaning.
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 action ('Contribute a relationship between existing nodes') and specifies that nodes can be identified by ids or names. This distinguishes it from sibling tools like 'upsert_node' and 'get_neighbors', making the 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?
No guidance on when to use this tool over alternatives (e.g., 'shortest_path', 'query_infra_graph'). It only mentions that evidence is required, which is a constraint rather than a usage condition. Lacks explicit when-to-use or when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Contribute a node the scanners missed. Evidence quotes required; recorded as INFERRED.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes | ||
| type | Yes | ||
| name | Yes | ||
| evidence | Yes | ||
| attrs | No | ||
| ambiguous | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the node will be recorded as INFERRED and evidence is required. However, it does not clarify the upsert behavior (update vs insert) or mention permissions, side effects, or other behavioral traits. Some value added but incomplete.
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 extremely concise—two clauses in one sentence. It is front-loaded with purpose. However, it sacrifices some clarity for brevity (e.g., 'contribute' could be more precise). Still, it's efficient and avoids 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?
Given the tool has 6 parameters, an output schema, and upsert behavior, the description is too brief. It does not explain data types, valid values for 'type', how existing nodes are handled, or the structure of the response. For a tool with many siblings, this lack of detail hinders correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter meanings. It only references 'evidence' (as required quotes). Other required parameters (node_id, type, name) and optional ones (attrs, ambiguous) are unexplained. This leaves the agent with minimal guidance beyond schema types.
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: to add nodes that scanners missed. It uses a specific verb ('contribute') and resource ('node'), and distinguishes from siblings like 'annotate_node' which would modify existing nodes. However, 'contribute' is slightly vague compared to 'add' or 'create', preventing a 5.
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 when scanners missed a node, and mentions evidence requirement. However, it does not explicitly state when NOT to use it or list alternatives. The context is clear but lacks exclusions or direct comparison to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify the outcome of a previously executed action (act-… record id).
| Name | Required | Description | Default |
|---|---|---|---|
| record_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose safety and behavior. It only indicates a read-like operation ('verify') but does not mention side effects, idempotency, or whether the action must be completed. Output schema exists but description does not clarify return structure.
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?
Single sentence that is front-loaded and to the point. No wasted words, though additional details could be included. Still efficient.
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 verification tool with one parameter and an output schema, the description hints at usage but does not describe the output (e.g., success/failure, details). Leaves some gaps for the agent.
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 has 0% description coverage, and the description only clarifies the ID format ('act-… record id') without explaining the parameter's purpose or constraints. Minimal added meaning beyond 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?
Description states specific action: verify outcome of a previously executed action, using a record ID. Clearly distinguishes from siblings like execute_action (runs action) and list_available_actions (lists 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?
Description implies use after executing an action but does not explicitly state when to use versus alternatives. No guidance on prerequisites or cases to avoid, leaving the agent to infer context.
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. Dates show when Glama detected each change.
annotate_nodeexecute_actionexplain_incidentfingerprint_systemgenerate_reportgenerate_viewget_access_contextget_auditget_enrichment_targetsget_logsget_neighborsget_nodeget_recent_errorsget_statelist_available_actionslist_dependencieslist_dependentslist_incidentslist_public_entrypointslist_runtime_workloadslist_servicesmap_infrastructurequery_infra_graphshortest_pathupsert_edgeupsert_nodeverify_actionEach tool targets a distinct operation or query: annotation, actions, incidents, fingerprinting, reports, views, graph queries, state, dependencies, entrypoints, runtime, services, etc. There is no functional overlap, and descriptions clearly differentiate them.
All tool names follow a consistent verb_noun pattern (e.g., annotate_node, get_state, list_services). No mixing of case or style, making the set predictable for an agent.
With 27 tools, the count exceeds the recommended range for a coherent set. While each tool serves a specific purpose, the overall surface is heavy and may overwhelm an agent, suggesting some consolidation is possible.
The tool set covers the full lifecycle of graph management (get, list, upsert, query) and domain-specific tasks (incidents, actions, dependencies). Minor gaps include the absence of delete operations for nodes/edges and limited incident modification tools.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Data-ontology maps of your business systems, served to AI agents over MCP.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Zero-secret MCP gateway for AI agents: risk-scored, audited calls with human-in-the-loop approval.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/adanb13/cirdan'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
