Simulate, test, and analyze cloud architectures without deploying real infrastructure. Cloud World Model enables AI agents to model cloud environments, evaluate architecture behavior and costs, run failure and chaos simulations, and explore infrastructure scenarios across cloud providers.
Scored across 9 tools
The tools are clearly separated into two domains: scenario discovery (scenario.list, scenario.get) and simulation control (simulation.create, delete, inject_failure, inject_traffic, metrics, recover_resource, step). Each tool has a distinct purpose with no overlapping functionality, and the descriptions reinforce the boundaries.
All tools follow a consistent pattern of `<domain>.<verb>` where domain is either scenario or simulation, and verbs are descriptive snake_case actions (list, get, create, delete, inject_failure, inject_traffic, metrics, recover_resource, step). This is a uniform, predictable convention.
With 9 tools, the set is well-scoped for the stated purpose of demoing cloud simulations. Each tool earns its place covering scenario lookup, simulation creation/deletion, traffic and failure injection, metrics reading, recovery, and time advancement.
The tool set covers the full lifecycle of a demo simulation: discover scenarios, create a simulation (with optional scenario hydration), control load and faults, observe metrics, recover resources, step through time, and delete the simulation. No obvious gaps that would hinder the core workflow.
Hydrate one built-in scenario from the live Cloud World Model scenario library. Prerequisite: a scenario id returned by scenario.list. Returns the complete selected scenario graph, including resources and connections plus optional seed, resilienceConfig, protectedResilienceConfig, traffic/failure presets, named traffic-phase summaries, activeFailurePhases and optionalFailurePhases (type, resource/zone target, severity, step range), retry-workload disclosure, and real-world incident metadata. The response includes both title and name for compatibility; pass resources and connections, and optionally seed/resilienceConfig, to simulation.create when you need to edit or inspect the graph. For the shorter handoff, pass the id as scenarioId instead. The likely next tool is simulation.create.
| Name | Required | Description | Default |
|---|---|---|---|
| scenarioId | Yes | Scenario identifier returned by scenario.list |
| Name | Required | Description |
|---|---|---|
| id | No | Stable scenario identifier |
| name | No | Scenario display name; equivalent to title |
| seed | No | |
| tags | No | |
| title | No | Scenario title |
| status | No | Result status; not_found when the requested scenario does not exist |
| message | No | Error or guidance message |
| category | No | |
| duration | No | |
| resources | No | Full resource graph; pass to simulation.create |
| difficulty | No | |
| connections | No | Full connection graph; pass to simulation.create |
| description | No | |
| primaryPurpose | No | Primary purpose of the scenario; absent means legacy purpose not specified |
| resilienceConfig | No | |
| realWorldIncident | No | |
| activeFailurePhases | No | |
| activeTrafficPhases | No | |
| optionalFailurePhases | No | |
| optionalTrafficPhases | No | |
| defaultTrafficPatterns | No | |
| retryTrafficDisclosure | No | |
| defaultFailureInjections | No | |
| protectedResilienceConfig | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the bar for behavioral disclosure is lower. The description adds useful behavior not in annotations: it returns the complete scenario graph, includes both title and name for compatibility, and can facilitate a shorter handoff when passing scenarioId. No contradiction with 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 essential purpose and prerequisite are front-loaded, but the middle section becomes a long run-on inventory of response fields and handoff options. The 'shorter handoff' sentence is ambiguous ('pass the id as scenarioId instead' of what?) and could be tightened without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, idempotent read tool with an output schema and rich annotations, the description is thorough: it supplies the prerequisite, return behavior, compatibility notes, and the expected next step (simulation.create). 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%, and the only parameter scenarioId already has a clear description. The description reinforces that scenarioId comes from scenario.list and can be used as shorthand for simulation.create, but that adds context rather than new 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 opens with a specific verb-resource pairing: 'Hydrate one built-in scenario from the live Cloud World Model scenario library.' It also differentiates from sibling scenario.list by requiring an id returned by that listing tool, so an agent can infer this is a single-item fetch, not enumeration.
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?
Explicitly states the prerequisite (scenario id from scenario.list), tells the agent to feed resources/connections to simulation.create when editing or inspecting, and identifies simulation.create as the likely next tool. It does not explicitly spell out when not to use it, but the workflow guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the built-in demo scenarios as compact catalog cards — stable IDs, title/name, description, difficulty, tags, category, duration, provider summary, resource/connection counts, named active/optional traffic phases, and retry-workload disclosure. Use it as the first call when you want a ready-made architecture instead of designing one; the cards intentionally omit resource, connection, traffic-pattern, and failure-injection graphs. Anonymous discovery includes only scenarios with at most 10 resources so every listed card is demo-creatable. No prerequisites. Optionally narrow discovery with provider, category, and/or difficulty filters; omit them to receive the complete demo-creatable catalog. Pass a returned id as scenarioId to simulation.create for server-side expansion, or pass it to scenario.get when you need to inspect the full graph. Larger scenarios require an authenticated session. Returns named activeFailurePhases and optionalFailurePhases with type, resource/zone target, severity, and step range. No API key required. The likely next tool is scenario.get.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Only scenarios in this category, such as scaling, failure, reliability, networking, or cost | |
| provider | No | Only scenarios that include resources from this cloud provider | |
| difficulty | No | Only scenarios at this difficulty level |
| Name | Required | Description |
|---|---|---|
| scenarios | Yes | Available demo scenarios |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, which covers safety. The description adds valuable context: the 10-resource limit for anonymous discovery (affects what is returned), no API key required, larger scenarios require authenticated session, and the return includes specific failure-phase details. This goes beyond annotations, describing what the result includes and access constraints. However, it doesn't detail what happens if filters are invalid or response size limits, which is minor.
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 block of 5 sentences, each packed with information. It's fairly long but every sentence contributes: purpose, omission of graphs, anonymous limit, filtering, usage of returned IDs, auth, return fields, next tool. Could be slightly more compact by splitting into bullets, but it's well-organized and front-loaded with the primary purpose.
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 moderate complexity (3 optional parameters, output schema present), the description covers when to use, what it returns (including details like failure phase names), prerequisites, auth requirements, and next-step routing. The presence of an output schema means return structure is already documented; the description complements with behavioral specifics like the 10-resource limit and anonymous discovery.
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% — all three parameters have descriptions in the schema. The description adds a bit of context: 'omit them to receive the complete demo-creatable catalog' and filter examples. But it doesn't add much beyond the schema. Since coverage is high, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List the built-in demo scenarios as compact catalog cards' with specific fields (stable IDs, title, description, difficulty, tags, etc.). It distinguishes itself from siblings by noting that it omits resource/connection/traffic/failure graphs, which are available via scenario.get. The verb 'list' and resource 'scenarios' are precise.
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?
Explicitly states when to use: 'Use it as the first call when you want a ready-made architecture instead of designing one.' It also tells when not to use (if you need the full graph, use scenario.get) and mentions prerequisites (none for anonymous, authentication for larger scenarios). Provides routing to 'simulation.create' and 'scenario.get' with returned IDs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a temporary anonymous demo cloud simulation from a list of resources and connections (max 2 active simulations per client, up to 10 resources; the returned simulationId is a short-lived unguessable capability that survives MCP transport teardown, but it is cleaned up when the demo lifetime expires or the simulation is deleted). No API key required for this temporary anonymous demo operation. Built-in scenario workflow: call scenario.list and pass a returned card's id as scenarioId to simulation.create for server-side graph expansion. For full control, call scenario.get and pass its hydrated resources and connections arrays instead. These are two alternatives — do not send scenarioId with resources or connections. For the catalog EKS Spot Interruption Migration scenario, you may set scenarioOverrides: { eksSpotInterruption: { startupSeconds } } with an integer startupSeconds from 0 through 3600 to test a different readiness deadline without copying the graph; this override requires scenarioId and is mutually exclusive with resources and connections. scenario.list returns graph-free cards with bounded active/optional traffic-phase and retry-workload summaries; it is not a source of resource, connection, traffic-pattern, or failure-injection graphs. Scenario traffic and failure presets are not applied automatically. Use it to start any simulation workflow — either with hydrated resources and connections from scenario.get or your own architecture. Do not use it to modify an existing simulation (use simulation.inject_traffic to change load). To give a resource an explicit capacity, set characteristics.capacityRps — the literal per-node RPS ceiling at which CPU reaches ~95%; do not use maxThroughput for this (it is a legacy internal scaling parameter with different semantics). Omitted capacityRps uses the selected catalog tier and can intentionally produce a stressed baseline (for example, the AWS m5.large catalog denominator is 2,000 RPS); for a healthy, capacity-bounded reliability experiment, declare an explicit per-node capacity such as 500 RPS. That value is an experiment control, not a universal hardware fact. Capacity, node-bound, SKU, and autoscaling values supplied through this MCP tool are recorded as agent-supplied in the immutable normalizationReceipt; request responseMode: 'full' to inspect it. Generic GKE telemetry and recovery apply only to worker nodes; the control-plane management fee is cost-only, with no modeled control-plane CPU, API throttling, or cooldown. To bound the autoscaled fleet size, set the top-level maxInstances / minInstances parameters. If you do not set maxInstances, the engine uses the provider default — AWS 50, GCP 15, Azure/OCI/DigitalOcean 10 — which may be much larger than your intended fleet size. The response includes effectiveMaxInstances / effectiveMinInstances so you can confirm the bounds that will be enforced. For a targeted CPU HPA scale-out threshold, send the canonical autoscalingTargetCpu field in this create call (for example, autoscalingTargetCpu: 70 for GKE). The compatible aliases scaleOutCpuThreshold, scaleOutCpuPercent, and autoscaleTargetCpuPercent are also accepted; if more than one is sent, their values must agree. Every create response includes hpaAudit with the supplied field, persisted thresholds, and any provider default. These four TOP-LEVEL fields are simulation-wide — the engine applies one CPU threshold identically to every resource's scale decision by default. To make ONE resource scale at a different CPU target than the rest of the simulation (e.g. a GKE cluster scaling out at 60% while an EC2 fleet in the same simulation scales out at 80%), set characteristics.scaleOutCpuThreshold and/or characteristics.scaleInCpuThreshold on that specific resource instead — the per-resource value wins over the simulation-wide default for that resource only. A misnamed near-miss field nested under characteristics (e.g. targetCPUUtilizationPercentage) is rejected with a 400 explaining the correct field name — it is never silently dropped and defaulted. Responses are compact by default: id, name, status, traffic, and a per-resource summary (id, name, status, cpuPercent, routedRps, availabilityState, isRoutable, and recoveryBlockedReason when provided). Pass responseMode: 'full' to get the complete simulation object instead. During a failure workflow, lower traffic to serviceable levels before calling simulation.recover_resource, then use simulation.step until the recovered resource is healthy. Recovery progress is included when applicable: recoveryProgress.state is parked, cooling_down, or healthy, and its parkWindow/cooldown objects report totalSteps, completedSteps, remainingSteps, target, and requiredSteps. Poll simulation.step until state is healthy, then use simulation.metrics to inspect the resulting state and metrics. No prerequisites. Returns the created simulation's id, which every other simulation.* tool consumes; the new simulation also becomes this session's current simulation, so subsequent per-simulation tools may omit simulationId. The likely next tool is simulation.step to advance time. Do not call api.spec to learn the simulation workflow — the tool descriptions in this session contain everything needed. Authenticate with an API key for unlimited persistent simulations.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Human-readable name for the simulation | |
| seed | No | Deterministic RNG seed for reproducible replays | |
| traffic | No | Initial traffic in requests per second (RPS) | |
| resources | No | List of cloud resources composing this simulation. For a built-in scenario, pass the hydrated resources from scenario.get; scenario.list cards are graph-free. (max 10 in demo mode; mutually exclusive with scenarioId) | |
| scenarioId | No | Live scenario identifier from scenario.list; mutually exclusive with resources and connections | |
| connections | No | Directed connections between resources. For a built-in scenario, pass the hydrated connections from scenario.get; scenario.list cards are graph-free. Directed edges should describe traffic flow between resources; omit when using scenarioId. | |
| description | No | Optional description of the simulation's purpose | |
| maxInstances | No | Hard ceiling on the autoscaled compute fleet size, stored as autoscalingConfig.maxInstances. If omitted, the provider default applies (AWS 50, GCP 15, Azure/OCI/DigitalOcean 10) — which may be much larger than your intended fleet size. | |
| minInstances | No | Floor on the autoscaled compute fleet size, stored as autoscalingConfig.minInstances. | |
| responseMode | No | Response detail level. 'compact' (default) returns id, name, status, traffic, and a per-resource summary (id, name, status, cpuPercent) — keeps the response small for agent loops. 'full' returns the complete simulation object including all resource characteristics and connections. | compact |
| resilienceConfig | No | Optional retry/cascade resilience model returned by scenario.get | |
| scaleOutCpuPercent | No | Grok-compatible alias for the CPU HPA scale-out target; if multiple target names are sent they must match. | |
| autoscalingTargetCpu | No | Canonical CPU HPA scale-out target percent. CWM synthesizes unrelated autoscaling defaults. | |
| scaleOutCpuThreshold | No | Equivalent alias for autoscalingTargetCpu; if both are sent they must match. | |
| autoscaleTargetCpuPercent | No | Grok-compatible alias for the CPU HPA scale-out target; if multiple target names are sent they must match. |
| Name | Required | Description |
|---|---|---|
| id | No | Unique simulation ID — use with simulation.step, simulation.metrics, etc. |
| name | No | Simulation name |
| status | No | Current simulation status |
| traffic | No | Current traffic in RPS |
| hpaAudit | No | CPU HPA create-time audit: whether a target arrived, its accepted field, the persisted thresholds, and the provider-default explanation when omitted. |
| resources | No | Per-resource summary (compact mode) or full resource states (full mode) |
| scenarioHash | No | Canonical SHA-256 of the persisted scenario graph and attached traffic-pattern order |
| replayIdentity | No | |
| normalizedConfig | No | Engine-resolved billing parameters for every resource: cost multipliers, hourly rates, autoscale thresholds (scaleOut/scaleIn CPU %), GPU SKU, per-node token throughput, billing floor, connection limits. Use this immediately after create to verify the simulation was set up as intended — e.g. confirm which GPU SKU was resolved, the effective billing floor, or the autoscale CPU threshold that will drive scale-out. |
| effectiveConfigHash | No | Canonical SHA-256 of the effective six-control startup configuration |
| scenarioAttribution | No | Trusted server-side attribution copied from the live scenario catalog; absent for explicit resource-graph creates |
| effectiveMaxInstances | No | The fleet-size ceiling the engine will enforce (autoscalingConfig.maxInstances, or the provider default when unset) |
| effectiveMinInstances | No | The fleet-size floor the engine will enforce (autoscalingConfig.minInstances, or the provider default when unset) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are sparse (only readOnlyHint=false, etc.), so the description carries the burden. It discloses mutability (creates a new simulation), temporary/anonymous nature, cleanup behavior, and limits on active simulations/resources. It also reveals that the operation is not idempotent (new simulationId each time) and explains recovery workflow. It does not explicitly state that it does not modify existing state, but the annotation destructiveHint=false is not contradicted. Overall, adds significant behavioral context beyond 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 excessively long (over 600 words) and covers many details that are already in the schema, such as specific parameter names and examples. While it has good structure (starts with core purpose, then alternatives, then detailed nuances), the verbosity makes it hard to scan. Every sentence does not earn its place; for instance, the detailed explanation of recovery workflow and hpaAudit could be truncated. Conciseness is a major weakness.
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 extreme complexity (15 params, nested objects, multiple conflicting alternatives), the description is remarkably complete. It explains the relationship between scenario.list and scenario.get, provides explicit guidance on mutual exclusivity, explains edge cases like default maxInstances, and describes the response modes. Although an output schema exists, the description still adds value by explaining recoveryProgress and responseMode. Nothing critical is missing for 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 100%, so the schema already documents every parameter. The description adds value by explaining key concepts like capacityRps vs maxThroughput, the mutual exclusivity of scenarioId with resources/connections, and the behavior of top-level autoscaling fields. However, much of this is also partially in schema descriptions (e.g., capacityRps description already mentions the intended use). Baseline 3 is appropriate since the schema covers the basics and the description adds some, but not extensive, additional 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 creates a temporary anonymous demo cloud simulation from resources/connections or a scenarioId, and explicitly differentiates from siblings by stating it does not modify existing simulations (use simulation.inject_traffic). It also covers the main alternative workflows. This is a specific verb+resource with strong sibling 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 when-to-use guidance: start any simulation workflow, use scenario.list/get for built-in scenarios, and explicitly states 'Do not use it to modify an existing simulation (use simulation.inject_traffic to change load)'. It also gives detailed alternatives for scenario vs full control, and even warns against using api.spec for workflow learning. This is exemplary routing and contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete an owned temporary anonymous demo simulation and its metrics, events, failures, and capability. This is the explicit way to free a simulation slot; deletion is irreversible, while the existing demo TTL remains the safety net for abandoned simulations. Prerequisite: a simulationId from simulation.create, or an active simulation in the preserved MCP session. The likely next tool is simulation.create to use the freed slot. A successful response is { deleted: true, id }; failed ownership checks do not delete or revoke anything. Authenticate with an API key to unlock all 62 tools and persistent simulation management.
| Name | Required | Description | Default |
|---|---|---|---|
| simulationId | No | Simulation ID returned by simulation.create. Preserve Mcp-Session-Id to omit this field and use the session's current simulation; if your connector starts a fresh MCP session for each call (for example Grok Bot or Cursor), pass this explicit ID after every fresh initialization. A fresh session has no current-simulation pointer and returns NO_ACTIVE_SIMULATION when the ID is omitted. Anonymous capabilities are short-lived (30 minutes by default), unguessable, and revoked when the demo expires or is deleted; proxy IP changes do not invalidate them. Do not treat the ID as a durable share link. |
| Name | Required | Description |
|---|---|---|
| id | No | ID of the deleted simulation |
| deleted | No | True when the simulation was deleted |
| simulationId | No | ID used for the deletion |
| simulationIdSource | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint and idempotentHint annotations, the description adds irreversibility, the list of deleted sub-resources, ownership-check failure semantics ('do not delete or revoke anything'), and the TTL safety net. It also mentions the auth requirement, going well beyond the structured hints.
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 opening sentence is front-loaded and decisive, and most sentences earn their place. The API-key 'unlock all 62 tools' sentence is somewhat tangential to deleting a simulation, but it does not obscure the core instruction.
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 one optional parameter, a high-coverage schema, annotations covering safety semantics, and an output schema present, the description covers prerequisites, failure behavior, and follow-up action. Nothing essential for selecting or invoking the tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the simulationId property is already richly documented, so the baseline is 3. The tool-level description adds prerequisite context and clarifies when to omit the parameter by relying on the session's active simulation, which helps an agent decide how to invoke it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: permanently delete an owned temporary anonymous demo simulation and its metrics, events, failures, and capability. It also distinguishes itself as the explicit way to free a simulation slot, clearly separating it from the sibling simulation.* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives prerequisites (a simulationId from simulation.create or an active simulation in the preserved MCP session), names the likely next tool (simulation.create), and contrasts with the demo TTL safety net. This provides concrete routing and sequencing guidance for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fail one node in a temporary anonymous demo simulation (the node is marked critical, not removed). No API key required for this temporary anonymous demo operation. Exact targeting: pass resourceName (human-readable name, e.g. 'app-server-01'; exact match preferred, an unambiguous prefix is accepted) or resourceId to fail a specific resource — including an individual named instance, not only a group. If resourceName matches multiple resources the call fails with a 400 listing every matching candidate by name — retry with one exact name (or its resourceId) from that list. If the resolved resource is not in a faileable state (already critical/warning) the call fails with a 400 describing its current status. When neither parameter is supplied, a RANDOM healthy node is selected — this path is non-deterministic and NOT suitable for controlled scenarios or replay; always target by name/id when reproducing a precise fault sequence. The response always echoes the applied outcome via resolvedResourceId, resolvedResourceName, and previousHealth (populated from the selected resource on the random path too). For typed failure injections (authenticated failure.create): instance_kill PERMANENTLY removes the instance — failure.delete does not restore it; use instance_down instead for a reversible single-node outage that is restored when the failure is deactivated or deleted. Returns the updated resource list and the failure event that was logged. The likely next tool is simulation.step to observe how the architecture degrades under failure, then simulation.metrics to review the health impact. Do not use it to advance simulation time — that is simulation.step. Pass simulationId from simulation.create when this call is made from a fresh MCP session; otherwise you may omit it to target the current simulation in the preserved MCP session. Authenticate with an API key to unlock all 62 tools including typed durational failures and chaos engineering.
| Name | Required | Description | Default |
|---|---|---|---|
| resourceId | No | Optional: ID of the resource to fail. Takes precedence over resourceName. | |
| resourceName | No | Optional: name of the resource to fail (exact match preferred; unambiguous prefix accepted). Ambiguous names return a 400 with a candidate list. | |
| simulationId | No | Simulation ID returned by simulation.create. Preserve Mcp-Session-Id to omit this field and use the session's current simulation; if your connector starts a fresh MCP session for each call (for example Grok Bot or Cursor), pass this explicit ID after every fresh initialization. A fresh session has no current-simulation pointer and returns NO_ACTIVE_SIMULATION when the ID is omitted. Anonymous capabilities are short-lived (30 minutes by default), unguessable, and revoked when the demo expires or is deleted; proxy IP changes do not invalidate them. Do not treat the ID as a durable share link. |
| Name | Required | Description |
|---|---|---|
| event | No | Failure event that was logged |
| resources | No | Updated resource list after failure injection |
| previousHealth | No | The resource's health status immediately before the failure was applied |
| resolvedResourceId | No | ID of the resource that was failed (targeted or randomly selected) |
| resolvedResourceName | No | Name of the resource that was failed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations. It discloses that the node is marked critical, not removed; that ambiguous names return a 400 with a candidate list; that non-faileable states return a 400; that the random path is non-deterministic; that the response echoes resolvedResourceId, resolvedResourceName, and previousHealth; and that instance_kill permanently removes the instance while instance_down is reversible. This is rich behavioral context that annotations (destructiveHint=true) only partially cover.
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 sentence earns its place: it covers targeting semantics, failure modes, random path caveats, response echoes, typed failure alternatives, next steps, and session handling. It is front-loaded with the core purpose and targeting rules. The only minor issue is that the authenticated failure.create digression and the '62 tools' marketing line are slightly tangential to immediate usage, but they do provide useful context.
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 (3 optional params, multiple failure modes, random vs targeted paths, session-dependent behavior), the description is remarkably complete. It covers what happens on success, on ambiguity, on non-faileable state, on random selection, and what the response contains. It also names the likely next tools (simulation.step, simulation.metrics) and the alternative for typed failures. The output schema exists, so return values need not be fully re-explained.
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%, so the schema already documents all three parameters. The description adds meaningful semantics beyond the schema: it explains the precedence of resourceId over resourceName, the exact-match/prefix behavior, the ambiguity failure mode, the random selection when neither is provided, and the session-context guidance for simulationId. This is valuable added meaning, though the schema already covers the basics.
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: fail one node in a temporary anonymous demo simulation. It distinguishes itself from siblings by explicitly noting it is not simulation.step (does not advance time) and by contrasting with simulation.inject_traffic and simulation.recover_resource. The verb 'fail' and resource 'node' are specific and 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 when-to-use guidance: use for failing a specific resource by name/id, or random selection for non-controlled scenarios. It explicitly warns against using the random path for controlled scenarios or replay, and names the alternative simulation.step for advancing time. It also explains when to pass simulationId (fresh MCP session) vs omit it (preserved session), and mentions the authenticated failure.create alternative for typed failures.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change the traffic load on a demo simulation. Omit traffic to trigger a random 2×–5× spike (sends random: true internally); provide traffic to set an absolute RPS level (capped at 10000 RPS in demo mode). Use it to stress-test the architecture before stepping; the change only affects metrics after the next simulation.step. Do not use it to read metrics (simulation.metrics) or advance time (simulation.step). Pass the simulationId returned by simulation.create when your connector opens a fresh MCP session; preserve Mcp-Session-Id to use the omitted-ID current-simulation default. Returns the updated simulation with its new traffic level; the likely next tool is simulation.step.
| Name | Required | Description | Default |
|---|---|---|---|
| traffic | No | Absolute traffic level in RPS to set. Omit to trigger a random spike instead. Server-capped at 10000 RPS in demo mode. | |
| simulationId | No | Simulation ID returned by simulation.create. Preserve Mcp-Session-Id to omit this field and use the session's current simulation; if your connector starts a fresh MCP session for each call (for example Grok Bot or Cursor), pass this explicit ID after every fresh initialization. A fresh session has no current-simulation pointer and returns NO_ACTIVE_SIMULATION when the ID is omitted. Anonymous capabilities are short-lived (30 minutes by default), unguessable, and revoked when the demo expires or is deleted; proxy IP changes do not invalidate them. Do not treat the ID as a durable share link. |
| Name | Required | Description |
|---|---|---|
| id | No | Simulation ID |
| status | No | Updated simulation status |
| traffic | No | New traffic level in RPS after injection |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since all annotations are false (not read-only, not idempotent, not destructive), the description carries the full burden of behavioral disclosure—and it succeeds. It reveals that omitting traffic causes a random 2×–5× spike, that RPS is capped at 10000, that changes only affect metrics after simulation.step, and that the tool can return NO_ACTIVE_SIMULATION without a valid session. There is no contradiction with 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 front-loaded with the core operation and every clause carries decision-relevant information. It is slightly dense, especially the final session/security caveats, which could benefit from bulletizing, but overall it is efficiently structured and appropriately sized for the tool's 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?
For a state-changing tool with an output schema, no required parameters, and false annotations, the description covers invocation variants, side effects, error cases, and the likely next step. An agent has everything it needs to select and call the tool correctly without consulting 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%, so the baseline is 3; however, the description adds substantial meaning beyond the schema. It explains when to omit traffic, the internal random flag, when to pass simulationId for fresh sessions, the current-simulation default, the NO_ACTIVE_SIMULATION error, and why the ID is not a durable share link. This far exceeds the schema's own 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 opens with a specific verb-resource pair ('Change the traffic load') and immediately states the tool's demo-simulation context. It then explicitly says what not to use it for, naming simulation.metrics and simulation.step, which clearly differentiates it from its siblings.
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 gives explicit when-to-use guidance ('use it to stress-test the architecture before stepping') and names the alternative tools for reading metrics and advancing time. It also tells the agent what to do next (simulation.step) and how to handle the session-sensitive simulationId, leaving no ambiguity about correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the latest metrics and resource states for a temporary anonymous demo simulation: latency, CPU, throughput, error rate, cost per hour, and per-resource health. Use it to inspect current state and metrics history without advancing time; do not use it to move the simulation forward — that is simulation.step. Responses are compact by default: principal current metrics plus explicit modeled goodputRps (a post-step point rate sourced from throughput, with provenance), goodputWindow (recorded only from persisted simulation-clock bounds, otherwise unavailable with provenance; never derive it from retrieval time or currentStep), errorBreakdown when available, per-resource status (id, name, status, cpuPercent, routedRps, availabilityState, isRoutable, and recoveryBlockedReason when provided), seeded EKS Spot checkpoint history and migrationEvaluationComplete/provenance when present, and the last 10 metrics-history entries. Pass responseMode: 'full' to get the complete simulation state, normalizedConfig, and full metrics history instead. During recovery, each resource may include recoveryProgress.state (parked, cooling_down, or healthy) with parkWindow and cooldown counters; poll simulation.step until healthy, then use simulation.metrics to inspect the resulting state and metrics. GPU / inference workflow: when the simulation includes a kubernetes resource with characteristics.inferenceMode: true, the response also includes top-level gpuUtilization (%), tokensPerSecond, costPerMillionTokens (USD/M tokens), idleGpuCostPerHour (USD/hr of standby GPU spend), and idleGpuFraction (0-1 idle HA overhead share) from the latest step, and each history entry carries the same inference fields. Pass the simulationId returned by simulation.create when your connector opens a fresh MCP session; preserve Mcp-Session-Id to use the omitted-ID current-simulation default. A fresh session has no current-simulation pointer. At least one simulation.step is needed for meaningful metrics. Read-only and free to repeat. The likely next tool is simulation.step or simulation.inject_traffic.
| Name | Required | Description | Default |
|---|---|---|---|
| responseMode | No | Response detail level. 'compact' (default) returns principal current metrics, errorBreakdown when available, per-resource status (id, name, status, cpuPercent, routedRps, availabilityState, isRoutable, recoveryBlockedReason, and failureLifecycle/routingState when provided), and only the last 10 metrics-history entries — keeps polling cheap for agent loops. 'full' returns the complete simulation object (all resource characteristics and connections) plus the entire metrics history. | compact |
| simulationId | No | Simulation ID returned by simulation.create. Preserve Mcp-Session-Id to omit this field and use the session's current simulation; if your connector starts a fresh MCP session for each call (for example Grok Bot or Cursor), pass this explicit ID after every fresh initialization. A fresh session has no current-simulation pointer and returns NO_ACTIVE_SIMULATION when the ID is omitted. Anonymous capabilities are short-lived (30 minutes by default), unguessable, and revoked when the demo expires or is deleted; proxy IP changes do not invalidate them. Do not treat the ID as a durable share link. |
| Name | Required | Description |
|---|---|---|
| metrics | No | Metrics history — bounded to the last 10 entries in compact mode, full history in full mode |
| traffic | No | Current traffic level in RPS |
| metricId | No | Storage-assigned ID of the latest persisted metric |
| errorRate | No | Latest error rate (%) |
| resources | No | Per-resource status summary (compact mode) |
| goodputRps | No | Modeled successful requests per second; a post-step point rate sourced from metrics.throughput |
| latencyP50 | No | Latest 50th-percentile latency in ms |
| latencyP95 | No | Latest 95th-percentile latency in ms |
| offeredRps | No | Latest aggregate offered requests per second |
| simulation | No | Complete simulation state (full mode only; absent in compact mode and when status is not_found/access_denied) |
| throughput | No | Latest effective requests per second |
| costPerHour | No | Latest estimated cost in USD/hr |
| currentStep | No | Current simulation time step |
| simulationId | No | ID of the queried simulation |
| goodputWindow | No | Interval goodput aggregate when every point has persisted simulation-clock bounds; otherwise status=unavailable. Never derive this from retrieval time or currentStep. |
| errorBreakdown | No | Validated additive error contributors from the latest metrics entry, in percentage-point units |
| gpuUtilization | No | Latest GPU utilization (%) — present only on GPU inference simulations |
| modeledShedRps | No | Latest aggregate modeled shed requests per second |
| idleGpuFraction | No | Latest share (0-1) of the GPU bill that is idle/standby capacity — present only on GPU inference simulations |
| tokensPerSecond | No | Latest inference throughput in tokens/second — present only on GPU inference simulations |
| goodputSemantics | No | Goodput is a point rate, not an interval total |
| goodputProvenance | No | Provenance for the modeled goodput field |
| idleGpuCostPerHour | No | Latest USD/hr of GPU spend funding idle/standby capacity (HA overhead) — present only on GPU inference simulations |
| costPerMillionTokens | No | Latest self-hosted inference cost in USD per million tokens (null when no tokens are being processed) — present only on GPU inference simulations |
| eksSpotInterruptions | No | Latest seeded EKS interruption telemetry, including additive migrationEvaluation/provenance when recorded. |
| metricsHistoryLength | No | Total number of metrics-history entries (compact mode returns only the last 10) |
| resilienceDiagnostics | No | Bounded resilience diagnostics from the latest step (compact mode). Absent when the resilience model did not run. |
| retryAmplificationFactor | No | Latest retry amplification factor (attemptedRps / originalRps). Values > 1.0 = amplification risk. null = model ran but no traffic. Absent = resilience model disabled. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds substantial behavioral context beyond them: compact vs. full response defaults, the last-10-history truncation, the fresh-session NO_ACTIVE_SIMULATION error, anonymous-session expiry, and provenance caveats for goodputWindow. It also clarifies that at least one simulation.step is needed for meaningful metrics.
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 and detailed, but it is organized into coherent sections: core purpose, response contents, recovery behavior, GPU workflow, and session handling. Every section carries actionable information, though some content overlaps with the schema's parameter descriptions, keeping it from being maximally 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 moderate complexity, an output schema, and strong annotations, the description is complete enough for an agent to call the tool correctly. It covers return-value specifics, default and full modes, error conditions, session semantics, recovery states, GPU inference fields, and the relationship to sibling tools.
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 baseline is 3, but the description adds extra meaning for both parameters. It explains the practical effect of responseMode on polling cost and agent loops, and it enriches simulationId with session-preservation guidance, fresh-session behavior, and object-lifetime caveats that are not in 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 opens with a specific verb and resource: 'Read the latest metrics and resource states for a temporary anonymous demo simulation,' and enumerates exactly what metrics are available. It also explicitly distinguishes itself from simulation.step by stating it should not be used to move the simulation forward, making the purpose unmistakable.
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 gives explicit when-to-use and when-not-to-use guidance: use it to inspect current state without advancing time, do not use it to advance the simulation, and use simulation.step instead for that. It also provides workflow direction such as 'poll simulation.step until healthy, then use simulation.metrics' and names simulation.inject_traffic as a likely next step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recover one reversible failed resource in a temporary anonymous demo simulation. No API key required for this temporary anonymous demo operation. Lower traffic to a serviceable level first, then provide resourceId or resourceName from simulation.create, simulation.step, or simulation.metrics. This deactivates applicable instance_down/database_overload failures for only the selected resource and returns recoveryProgress with parked, cooling_down, or healthy state plus cooldown counters. It cannot restore an instance_kill because that failure permanently removes the resource. The likely next tool is simulation.step; keep stepping and inspect the targeted resource until recoveryProgress.state is healthy. Pass simulationId from simulation.create when using a fresh MCP session; a preserved session may omit it. Authenticate with an API key to unlock all 62 tools and unlimited simulations.
| Name | Required | Description | Default |
|---|---|---|---|
| resourceId | No | ID of the failed resource to recover | |
| resourceName | No | Exact case-insensitive name of the failed resource to recover | |
| simulationId | No | Simulation ID returned by simulation.create. Preserve Mcp-Session-Id to omit this field and use the session's current simulation; if your connector starts a fresh MCP session for each call (for example Grok Bot or Cursor), pass this explicit ID after every fresh initialization. A fresh session has no current-simulation pointer and returns NO_ACTIVE_SIMULATION when the ID is omitted. Anonymous capabilities are short-lived (30 minutes by default), unguessable, and revoked when the demo expires or is deleted; proxy IP changes do not invalidate them. Do not treat the ID as a durable share link. |
| Name | Required | Description |
|---|---|---|
| simulationId | No | |
| recoveryState | No | |
| previousHealth | No | |
| stepsToHealthy | No | |
| recoveryProgress | No | |
| resolvedResourceId | No | |
| simulationIdSource | No | |
| resolvedResourceName | No | |
| deactivatedFailureIds | No | |
| stepsToHealthyIsLowerBound | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are sparse (all false), so the description carries the transparency burden. It clearly discloses side-effect scope ('for only the selected resource'), return-state semantics (parked, cooling_down, healthy, cooldown counters), unrecoverable failure behavior, anonymous session constraints, and API-key/auth implications. This goes well beyond what the annotations convey.
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 front-loaded with purpose and prerequisites and stays organized, but it repeats 'temporary anonymous demo' and closes with a somewhat promotional API-key line ('unlock all 62 tools') that is tangential to correct invocation. Slightly longer than necessary, but not wasteful enough to drop below 4.
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 schema, annotations, and output schema, the description covers all information an agent needs: preconditions, exact recoverable failure types, parameter provenance, session handling, auth constraints, and post-recovery next step. There are no obvious gaps that would cause mis-selection or mis-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?
Input schema coverage is 100%, so the baseline is 3; the description adds meaning anyway by stating that resourceId or resourceName should come from prior simulation tools and implying one of them must be supplied. It also restates the simulationId fresh-session rule, which is already in the schema, so the added value is real but modest.
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 first sentence names the exact action and scope: 'Recover one reversible failed resource in a temporary anonymous demo simulation.' It also distinguishes recoverable failure types (instance_down/database_overload) from the unrecoverable instance_kill, leaving no ambiguity about what this tool does relative to siblings like simulation.inject_failure or simulation.step.
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 gives an explicit precondition ('Lower traffic to a serviceable level first'), tells where to get the ID ('from simulation.create, simulation.step, or simulation.metrics'), and states a when-not case ('It cannot restore an instance_kill'). It also recommends the next action: use simulation.step and inspect until recoveryProgress.state is healthy.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Advance a temporary anonymous demo simulation by one time step and return updated metrics — CPU, latency, throughput, error rate, cost (max 20 persisted steps per demo). Use it to observe how the architecture behaves over time, typically right after simulation.create or simulation.inject_traffic. Do not use it to read current state without advancing time — that is simulation.metrics. Pass the simulationId returned by simulation.create when your connector opens a fresh MCP session; preserve Mcp-Session-Id to use the omitted-ID current-simulation default. The likely next tool is simulation.step again (to keep observing) or simulation.inject_traffic (to change load first). Responses are compact by default: principal metrics plus per-resource status (id, name, status, cpuPercent, routedRps, availabilityState, isRoutable, and recoveryBlockedReason when provided) and this step's events. Seeded characteristics.eksSpotInterruption telemetry retains its additive migrationEvaluation beside the interruption lifecycle: use its recorded/derived/unavailable field provenance, frozen deadline verdict/counts/reasons, and simulation-clock milestones rather than final service health. The distinct eksSpotMigration contract remains separately reported when configured. Compact responses also include errorBreakdown when the engine provides it. A critical resource with isRoutable: true is degraded but still serving; availabilityState: unavailable and isRoutable: false identify a failed or parked node. Pass responseMode: 'full' to get the complete simulation state instead. During recovery, each resource may include recoveryProgress with state parked, cooling_down, or healthy, plus parkWindow and cooldown counters. Poll simulation.step until the targeted resource's recoveryProgress.state is healthy, then use simulation.metrics to inspect the resulting state and metrics. GPU / inference workflow: when the simulation includes a kubernetes resource with characteristics.inferenceMode: true, each step response also includes gpuUtilization (%), tokensPerSecond, costPerMillionTokens (USD/M tokens), idleGpuCostPerHour (USD/hr of standby GPU spend), and idleGpuFraction (0-1 idle HA overhead share) so you can track inference economics step by step. Authenticate with an API key for unlimited steps and GPU right-sizing hints.
| Name | Required | Description | Default |
|---|---|---|---|
| responseMode | No | Response detail level. 'compact' (default) returns only principal metrics, errorBreakdown when available, per-resource status (id, name, status, cpuPercent, routedRps, availabilityState, isRoutable, recoveryBlockedReason, and failureLifecycle/routingState when provided), and this step's events — keeps observations small for agent loops. 'full' returns the complete backend step response including the entire simulation object with all resource characteristics and connections. | compact |
| simulationId | No | Simulation ID returned by simulation.create. Preserve Mcp-Session-Id to omit this field and use the session's current simulation; if your connector starts a fresh MCP session for each call (for example Grok Bot or Cursor), pass this explicit ID after every fresh initialization. A fresh session has no current-simulation pointer and returns NO_ACTIVE_SIMULATION when the ID is omitted. Anonymous capabilities are short-lived (30 minutes by default), unguessable, and revoked when the demo expires or is deleted; proxy IP changes do not invalidate them. Do not treat the ID as a durable share link. |
| Name | Required | Description |
|---|---|---|
| events | No | Events generated during this step |
| metrics | No | Full-mode backend metric record; migrationEvaluation is exact-typed when a seeded interruption is present. |
| traffic | No | Current traffic level in RPS |
| metricId | No | Storage-assigned persisted metric ID when available |
| errorRate | No | Error rate (%) |
| resources | No | Per-resource status summary (compact mode) |
| goodputRps | No | Modeled successful requests per second; a post-step point rate sourced from metrics.throughput |
| latencyP50 | No | 50th-percentile latency in ms |
| latencyP95 | No | 95th-percentile latency in ms |
| offeredRps | No | Aggregate offered requests per second represented by metrics.offeredRps provenance |
| throughput | No | Effective requests per second |
| costPerHour | No | Estimated cost in USD/hr |
| currentStep | No | New simulation time step index |
| scenarioHash | No | Canonical SHA-256 of the persisted scenario graph and attached traffic-pattern order |
| simulationId | No | ID of the stepped simulation |
| goodputWindow | No | Interval goodput aggregate when every point has persisted simulation-clock bounds; otherwise status=unavailable. Never derive this from retrieval time or currentStep. |
| errorBreakdown | No | Validated additive error contributors in percentage-point units; separates pool/DB, compute, capacity, CPU, storage, runtime-memory, and queue absorption effects |
| gpuUtilization | No | GPU utilization (%) — present only on simulations with a GPU inference kubernetes resource |
| modeledShedRps | No | Aggregate modeled requests per second shed by bounded capacity |
| replayIdentity | No | |
| idleGpuFraction | No | Share (0-1) of the GPU bill that is idle/standby capacity — present only on GPU inference simulations; values above 0.5 mean over half the GPU spend is HA overhead |
| tokensPerSecond | No | Inference throughput in tokens/second — present only on GPU inference simulations |
| goodputSemantics | No | Goodput is a point rate, not an interval total |
| goodputProvenance | No | Provenance for the modeled goodput field |
| idleGpuCostPerHour | No | USD/hr of GPU spend funding idle/standby capacity (HA overhead) — present only on GPU inference simulations |
| effectiveConfigHash | No | Canonical SHA-256 of the effective six-control startup configuration |
| costPerMillionTokens | No | Self-hosted inference cost in USD per million tokens (null when no tokens are being processed) — present only on GPU inference simulations |
| eksSpotInterruptions | No | Seeded EKS interruption telemetry, including the authoritative additive migrationEvaluation when recorded. |
| resilienceDiagnostics | No | Bounded resilience diagnostics summary (compact mode). Absent when the resilience model did not run. Use simulation.compare_resilience for full per-path detail. |
| retryAmplificationFactor | No | Retry amplification factor for this step (attemptedRps / originalRps). Values > 1.0 = amplification risk. null = model ran but no traffic. Absent = resilience model disabled. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate readOnly=false and idempotent=false, but the description adds substantial behavioral detail: max 20 persisted steps, compact vs full response shapes, recoveryProgress lifecycle, GPU-specific metrics, session-scoped simulation ID behavior, NO_ACTIVE_SIMULATION failure mode, and anonymous capability revocation. There is no contradiction with 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 core purpose and usage rules are front-loaded, and nearly every sentence adds operational value. However, the description is one dense paragraph with highly domain-specific asides (eksSpotInterruption, eksSpotMigration, GPU inference economics) that could have been better organized or trimmed without losing essential guidance.
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 state-advancing tool with zero required parameters but complex session semantics, the description covers invocation context, alternatives, failure modes, response interpretation, recovery polling, and authentication. Even with an output schema present, it adds interpretation guidance that an agent needs to correctly drive the simulation loop.
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 goes well beyond baseline by explaining the practical meaning of both parameters: responseMode compact/full output differences, and simulationId omission semantics tied to Mcp-Session-Id, including fresh-session failure behavior and the non-durable, unguessable nature of the ID.
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 and resource: 'Advance a temporary anonymous demo simulation by one time step and return updated metrics'. It also explicitly distinguishes itself from simulation.metrics, stating 'Do not use it to read current state without advancing time — that is simulation.metrics.' This makes the tool's role 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?
Usage context is explicit: 'typically right after simulation.create or simulation.inject_traffic', with a clear exclusion for reading state without advancing. It also names likely next tools and provides a concrete recovery polling workflow: 'Poll simulation.step until recoveryProgress.state is healthy, then use simulation.metrics.'
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.
scenario.get3 fields changedOutput schema / properties / activeFailurePhases / items / properties / targetProviderAdded value: +{
+ "enum": [
+ "aws",
+ "gcp",
+ "azure",
+ "oci",
+ "digitalocean"
+ ],
+ "type": "string"
+}Output schema / properties / activeFailurePhases / items / properties / targetRegionAdded value: +{
+ "type": "string"
+}Output schema / properties / activeFailurePhases / items / properties / type / enumPrevious value: -[
- "instance_kill",
- "instance_down",
- "az_outage",
- "database_overload",
- "network_latency",
- "spot_interruption"
-]New value: +[
+ "instance_kill",
+ "instance_down",
+ "az_outage",
+ "region_outage",
+ "permanent_data_loss",
+ "database_overload",
+ "network_latency",
+ "spot_interruption"
+]scenario.list3 fields changedOutput schema / properties / scenarios / items / properties / activeFailurePhases / items / properties / targetProviderAdded value: +{
+ "enum": [
+ "aws",
+ "gcp",
+ "azure",
+ "oci",
+ "digitalocean"
+ ],
+ "type": "string"
+}Output schema / properties / scenarios / items / properties / activeFailurePhases / items / properties / targetRegionAdded value: +{
+ "type": "string"
+}Output schema / properties / scenarios / items / properties / activeFailurePhases / items / properties / type / enumPrevious value: -[
- "instance_kill",
- "instance_down",
- "az_outage",
- "database_overload",
- "network_latency",
- "spot_interruption"
-]New value: +[
+ "instance_kill",
+ "instance_down",
+ "az_outage",
+ "region_outage",
+ "permanent_data_loss",
+ "database_overload",
+ "network_latency",
+ "spot_interruption"
+]
Add one secure layer between your agents and this server.