chaos-core-mcp

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that the tool can have side effects, aligns with destructiveHint=true, and adds depth: each step is policy-checked individually, DENY/REQUIRE_APPROVAL steps are reported as failed/skipped, and all decisions are recorded to an audit trail. It even states transport invariance (stdio/HTTP) regarding policy enforcement, which is valuable context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every part serves a purpose: core functionality, policy details, parameter explanations, return structure, usage examples, and error handling. It is front-loaded with the primary purpose and logically organized. No wasted sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is exhaustive for a complex tool: it covers side effects, policy behavior, both invocation modes, output format details, error handling (plan_id not found), and the fact that step failures don't throw. It even provides a full JSON response structure. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

While the schema already describes all parameters (100% coverage), the description adds meaningful nuance: the relationship between plan_id and steps (alternatives), the confirmed flag's role in running REQUIRE_APPROVAL steps, and the dry_run option to avoid side effects. It also clarifies the response_format's human vs. machine readability. This enriches the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: executing a plan or inline steps through the Cognitive Core loop. It distinguishes from siblings by noting it's the only tool that can have side effects, and it specifies the pipeline (policy check, capability selection, execution, evaluation). This is a specific verb+resource with clear differentiation.

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 explicit usage scenarios: 'Use when: You have a plan_id from chaoscore_plan and are ready to run it', and 'Use when: A step came back REQUIRE_APPROVAL and you've now confirmed with the user'. It also gives a clear exclusion: 'Don't use when: You just want to see what a plan would do without side effects -> use dry_run=true'. This is excellent guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

While annotations already declare readOnlyHint=true and destructiveHint=false, the description adds critical context beyond those: it never reveals credentials, and clarifies process-wide vs session-scoped state (e.g., capabilities are global, last_* are per-session). It also discloses error behavior ('never errors under normal use'). This enriches the agent's understanding of side effects and safety without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (main purpose, Args, Returns, Examples, Error Handling). It front-loads the core purpose and scope, then provides just enough detail per target. Every sentence earns its place—examples are actionable and error handling is concise. It is comprehensive without being redundant.

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 2 parameters with full enum coverage, no output schema, and read-only annotations, the description is remarkably complete. It explains return values for every target, clarifies session vs process-wide scope, addresses credential safety, and covers error handling. An agent has everything needed to invoke it correctly and interpret results.

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 already fully describes both parameters with enums and descriptions (schema coverage 100%). The description's Args section restates the targets but adds value by coupling each target to its return shape in the Returns section (e.g., 'capabilities' returns {name, description, risk, ...}). This goes beyond the schema's generic phrasing and helps the agent anticipate output, though the schema already handles the basic parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it is a read-only introspection tool for Chaos Core's state, listing specific targets (capabilities, policy, providers, memory, audit, session, last_*). It explicitly says 'Never modifies anything' and differentiates from sibling tools (reason/plan/execute) by focusing on inspection. The verb and resource are precise, and the scope is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit examples of when to use this tool: 'What can this server actually do?' -> capabilities, 'Which model is actually answering...' -> providers, 'Why did that step get blocked?' -> policy/audit. This gives clear usage conditions and implicitly contrasts with the mutating siblings. It also states the tool is read-only, reinforcing appropriate use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds valuable context beyond them: planning is explicitly 'NOT authorization to act — policy checks happen at execution time, per step', and it clarifies that no execution occurs. It also discloses provider-configuration error behavior ('OPENAI_API_KEY is not set'). No contradiction with any annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every section earns its place: since no output schema exists, the 'Returns' JSON block is essential, and the error-handling section covers realistic failure modes. It is well-structured with clear headers and front-loads the core purpose before details. Slight redundancy between the Returns block and the parameter glossary keeps it from a 5.

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 moderately complex tool (4 params, 2 enums, no output schema, with 5 siblings), the description covers purpose, usage boundaries, return shape, and errors comprehensively. It explains the capability-registry constraint and how to discover valid capabilities via chaoscore_inspect. Minor gaps remain (e.g., no mention of plan length limits or cancellation), but nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters, giving a baseline of 3. The description adds marginal value by hinting that context should include prior chaoscore_reason output, but repeats most parameter purpose verbatim rather than deepening it. Adequate given the schema's completeness.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-resource pair ('Produce an ordered, executable plan for an objective') plus a hard scoping constraint ('using ONLY capabilities currently in the capability registry'). It explicitly positions itself as 'the Planner stage of the Cognitive Core loop' and states what it is not — 'Planning does NOT execute anything' — which cleanly distinguishes it from the sibling chaoscore_execute.

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 contains explicit 'Use when' and 'Don't use when' examples, names chaoscore_execute as the follow-up, tells the agent to pass the returned plan.id to it, and instructs that prior chaoscore_reason output should be placed into the context parameter. Guidance on when to use vs. alternatives is fully spelled out with no inference required.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint annotation, the description discloses that the tool does not take action, uses the active AI provider, and includes specific error-handling behavior if the provider is not configured. It also describes the return structure for JSON format. This adds significant richness beyond the annotations and fully explains the tool's non-mutating, provider-dependent nature.

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 well-structured with clear sections: purpose, pipeline placement, what it does not do, args, returns, examples, and error handling. It is front-loaded with the primary purpose and every section adds value. The length is justified by the inclusion of a return schema (since no output schema is provided) and error handling, making it efficient rather than verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for an agent to call this tool correctly. It covers the input parameters, provides a return schema for JSON format, explains the provider dependency and how to inspect it (see chaoscore_inspect), gives usage examples, and documents error cases. With no output schema present, the included return structure is essential and well-provided.

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 100%, so baseline is 3. The description adds a bit of extra clarity, e.g., for 'context' it specifies the exact structure '[source, content]' and for 'response_format' it notes the default. It also explicitly lists enum values and says 'empty array if none.' While mostly redundant with the schema, it provides a slightly more concise and action-oriented explanation, justifying a 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 states a specific action ('Analyze an objective and its context BEFORE committing to a plan') with a clear resource (the objective and context) and delivers structured analysis. It explicitly distinguishes itself from siblings: 'Does NOT produce an executable plan... call chaoscore_plan next.' The purpose is unambiguous and differentiates well from chaoscore_plan, chaoscore_execute, 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?

Provides concrete when-to-use and when-not-to-use guidance with an example ('Should I migrate memory storage...?') and explicitly references the alternative ('use chaoscore_plan directly'). It also frames this as the first stage in the Cognitive Core loop, giving clear context for when this tool should be invoked.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond these: expired records are never returned, the store is durable across transports, and miss returns are non-error strings/empty arrays. No contradictions with annotations are present.

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 well-organized into sections (Args, Returns, Examples, Error Handling) with the core purpose front-loaded. Every sentence serves a purpose; there is no fluff or repetition. Despite its length, it remains efficient and scannable.

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 six parameters and no output schema, the description fully covers behavior: it documents both markdown and JSON return structures, error handling for misses, pagination fields, and example use cases. An agent has all necessary information to call it correctly without external documentation.

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 100%, but the description enriches parameter understanding by explaining interaction effects (e.g., 'key' ignores other filters), pagination semantics (offset, has_more, next_offset), and response format differences. It also provides concrete examples that map parameters to real queries, going well beyond bare 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 opens with a specific verb ('Search') and resource ('Semantic Memory records'), and explicitly distinguishes itself from chaoscore_remember ('previously stored with chaoscore_remember'). It lists the three supported search modes (exact key, substring, tag filtering), leaving no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides explicit use cases with examples ('What do we know about staging?' -> query='staging') and a clear exclusion ('Don't use when: You want to write/update a memory -> use chaoscore_remember instead'). This gives an agent precise decision criteria for choosing this tool over its sibling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate idempotent, non-read-only, and non-destructive. The description goes further: it explains durable SQLite-backed storage, persistence across sessions/restarts/transports, overwrite semantics with timestamp updates, TTL behavior (exclusion from recall), and error handling. This exceeds annotation coverage without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (Args, Returns, Examples, Error Handling) and front-loads the core purpose. Every sentence conveys necessary information without redundancy, making it appropriately concise for a tool with this complexity.

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 (5 params, TTL, transport independence, output formats) and lack of an output schema, the description covers all needed aspects: purpose, usage, params, return format, error handling, and examples. An agent can confidently invoke this 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?

Schema description coverage is 100%, so the schema already documents all parameters. The description repeats most parameter details and adds minor clarifications (e.g., TTL expiration behavior, key uniqueness), but does not significantly augment the schema. Baseline 3 is appropriate when schema handles the heavy lifting.

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 it persists key/value records to Semantic Memory for later retrieval via chaoscore_recall. It specifies the resource (Semantic Memory), the verb (persist), and distinguishes itself from the recall sibling by explicitly naming it as the retrieval counterpart.

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?

An explicit 'Examples' section provides a concrete use case ('Remember that the staging DB uses the Melbourne region') and a don't-use case ('You need to search existing memories -> use chaoscore_recall instead'). This directly instructs when to use versus when to use the sibling, leaving no ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.