whatif

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

The description contradicts the annotations. Annotations state idempotentHint=false and destructiveHint=true, but the description says 'Storing the same from/to/transform twice returns the same id' (idempotent) and 'does not touch either model' (non-destructive). This is a direct contradiction, so the description fails to align with the declared metadata.

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 dense single paragraph that front-loads the primary action and then packs exclusions, discoverability, and duplicate behavior with no filler. It could be split into sentences for readability, but every clause earns its place given 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?

Given no output schema, the description adequately covers the return value ('the id this returns'), side effects (Relation recorded automatically), limitations (no validation/run), and discoverability. It references ROADMAP.md for deeper context. It does not elaborate on error conditions or the exact Binding structure, but the core call semantics are 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the port-connection semantics ('fromModel's fromPort feeding toModel's toPort'), the transform field's free-text nature ('Not yet interpreted by anything'), and the content-addressed duplicate behavior. This goes beyond the schema's property 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 states the specific verb 'Record' and resource 'an intended connection between two stored models' declared ports', clarifying it creates a content-addressed Binding. It distinguishes itself from sim_link by referencing 'sim_link's Relation graph' and explicitly frames the tool as a proposal that does not validate or run.

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

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

The description provides clear context on when this tool is appropriate: to create a non-validated, non-executed connection proposal. It also tells how results are discoverable (sim_edges, sim_get_binding). However, it does not explicitly name when to prefer sim_bind over sim_link or other siblings, nor state exclusions.

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?

The description extensively discloses behavior beyond annotations: it returns a new content-addressed model rather than mutating the original, explains how instant-pickup transitions and delay transitions are handled, and warns that learned values on non-replayable structure are unreliable. No contradiction with annotations (destructiveHint: true, readOnlyHint: false) — it clarifies the actual effect.

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 each sentence carries weight, covering input format, learning logic, output interpretation, and caveats. It's front-loaded with the core purpose and then systematically explains nuances. Slightly dense, but no wasted words given the 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 tool with this complexity (rates, delays, conformance reports, evidence fields), the description is remarkably complete. It explains output semantics (fittingPercent vs tokenFitness, rateEvidence fields like n, gapCV, insufficient) and provides actionable guidance on trust. Nothing critical is missing for an agent to call it correctly.

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

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

Schema coverage is 100% for both parameters, but the description adds substantial meaning: it specifies the exact CSV format (case_id, activity, timestamp) and clarifies that activities are transition ids. This goes beyond the schema's terse descriptions and is essential for correct invocation.

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 'Calibrate a model against YOUR event log' — a specific verb (calibrate) and resource (model). It clearly differentiates from sibling tools like sim_evaluate or sim_conformance by focusing on learning rates from observed timings. The purpose 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?

It provides context on when to use it (when you have an event log to fit against) and gives interpretation guidance (read fittingPercent over tokenFitness). However, it doesn't explicitly contrast with alternative tools or state when not to use it, leaving some inference to the agent.

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 declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true. The description adds substantial behavioral context beyond annotations: it returns non-trivial automorphism orbits and generator count, zero generators means rigid, and it refuses as a tool error rather than silently falling back when the exact search exceeds its budget. It also explains the relationship to content-addressed ids from sim_get_model. The only minor gap is that it doesn't explicitly state whether the operation mutates anything, but the annotations already cover destructiveHint=true, and the description's focus on computation and return values is consistent with that.

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 dense but every sentence earns its place: it defines the tool's purpose, distinguishes it from sim_classify, explains the relationship to sim_get_model, describes return values, and states the failure mode. It is front-loaded with the core purpose and scoping. It is somewhat long, but the complexity of the tool (exact vs WL isomorphism, fallback behavior, budget limit) justifies the length. No wasted words.

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

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

For a tool with one parameter, no output schema, and complex behavioral nuances, the description is complete. It covers what the tool returns (canonicalId, orbits, generator count), how to interpret the results (zero generators = rigid), when to use it vs alternatives, and when it fails (budget exceeded). An agent has everything needed to select and 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%: the only parameter 'id' is described as 'model id' in the schema. The description adds context by explaining that the model id from sim_get_model is not the id to compare, and that the canonicalId is the one to use. However, it doesn't add syntax or format details beyond what the schema provides. Baseline 3 is appropriate because the schema already documents the parameter fully.

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 ('Tell whether two differently-labelled models are actually the same net') and a specific resource (an isomorphism-invariant id computed from exact automorphism orbits). It clearly distinguishes itself from sim_classify by naming the exact vs colour-refinement (WL) distinction and the fallback behavior. An agent can tell this tool apart from sim_classify and sim_get_model without opening schemas.

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

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

The description explicitly says when to use this tool: compare canonicalId rather than model id when checking whether a catalog already holds a net. It also names the alternative (sim_classify) and the condition that selects it: sim_classify's fallback covers the case when the exact search can't decide, for classification specifically. It also states when the tool refuses (exceeds 200,000-leaf budget), which is a clear exclusion condition.

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?

Goes well beyond the annotations by explaining the exact-versus-sampled verification behavior, the candidate status without verify, and which JSON-LD fields are user-editable versus derived. It does not elaborate on the destructive side effect implied by destructiveHint, but it does not contradict the annotations either.

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 dense but front-loaded with the core purpose in the first clause. Each subsequent clause adds necessary behavioral or contract detail. The parentheticals make it heavier than ideal, but the information is specific and 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?

For a complex tool with no output schema, the description covers the main return shape, editable fields, verification behavior, and points to the full docs for the caveat. It is complete enough for an agent to invoke it correctly, though the colour-refinement caveat is deferred rather than 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?

The schema already documents all three parameters, so the baseline is 3. The description adds meaningful semantics around verify=true (exact proof, fallback, candidate classes) and clarifies the inline_context behavior by noting the URL resolves to the identical map. That extra context raises it to 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?

States a specific action ('Discover the parameter classes of a stored model'), the resource, and the output format (JSON-LD with editable annotation slots). The purpose is clearly distinguished from the broader sibling list by focusing on classification rather than binding, calibration, or verification.

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?

Gives clear context on how to use the verify flag, including the exact automorphism proof, the sampled fallback, and the 200,000-leaf budget. It also tells the agent to read the classification docs for the caveat. It does not explicitly name alternative tools or when not to use it, so it stops short of a 5.

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

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

The description goes well beyond the annotations by disclosing that it depends on a configured LLM, creates a new owned model, returns a new id on success, and returns raw model JSON plus validation errors on failure. It also gives a concrete remediation path. This meaningfully enriches the annotation hints without contradicting them.

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

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

The description is three sentences, front-loaded with the core purpose, then covers the endpoint equivalence, refusal condition, and return/fallback behavior. Every sentence adds distinct value and there is no redundant or filler text.

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 four parameters and no output schema, the description is remarkably complete: it explains success and failure return behavior, the LLM dependency, ownership of the new model, and how to recover manually. Nothing essential 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 all four parameters. The description adds no parameter-level detail beyond mentioning focus options, which are already listed in the schema, so the baseline score of 3 applies.

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: derive a Petri-net model from source code, validate it, and store it as a new model the caller owns. It also distinguishes this from manual creation by mentioning the same generator as /api/code-to-flow and the fallback to sim_create_model.

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 clear context: use this to generate a validated Petri-net model from source code with an LLM. It also tells the agent when it will fail (no LLM provider configured) and how to recover (fix the JSON and call sim_create_model), though it does not explicitly enumerate exclusions against other sibling tools.

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?

The description discloses rich behavioral details beyond the annotations: server-enforced shared seed, summary vs full output sizes, metrics included, time-weighted sampling behavior, scenario-level summary override, and engine-dependent seed effects. The annotations already flag destructive/open-world characteristics, lowering the burden on the description.

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 dense but every sentence earns its place, covering purpose, key caveats, defaults, and engine rules without fluff. The main behavior is front-loaded, and the more technical constraints follow naturally.

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 no output schema, the description compensates by naming the default summary metrics, warning about full output size, listing defaults, and clarifying seed/engine behavior. An agent has enough information to invoke the tool correctly and interpret what it returns.

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?

Even though schema coverage is 100%, the description adds substantial meaning: defaults for hours, samples, and realizations; the full=true consequence of large trajectories; the interplay with scenario-level 'summary': true; and per-scenario engine selection. This goes far beyond the schema's one-line parameter descriptions, especially for 'full' and 'scenarios'.

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 opening sentence states a specific operation: 'Run several scenarios against one model on one shared seed and return them side by side.' This clearly identifies the tool's purpose and distinguishes it from scenario-creation or pipeline tools like sim_scenario and sim_run_pipeline.

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 strong usage context: default summary output, when to pass full=true, per-scenario summary override, default hours/samples/realizations, and legitimate cross-engine comparisons. It does not explicitly name alternative tools or exclusions, but it provides enough context for an agent to use it correctly.

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?

The description says 'List the component registry' which clearly implies a read-only operation, but the annotations declare destructiveHint: true. This is a direct contradiction – the description does not disclose any destructive behavior and instead suggests a non-mutating action. No additional behavioral context is provided beyond this 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 two sentences long and packs relevant information: the resource being listed, the types of templates, the content of each entry, and a pointer to the next step. It is slightly verbose with the parenthetical list of template types, but this is informative and aids 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?

The description explains the output format (ports, params, discipline notes) and how to proceed after listing (compose with sim_compose). It is complete for a listing tool with no parameters and no output schema. However, the contradiction with the destructiveHint annotation introduces confusion about whether the tool has side effects, which detracts from 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?

There are zero parameters, and the schema coverage is 100% (since no params exist). The description adds value by explaining what the registry entries contain (ports, params, discipline notes), which helps the agent understand the output structure. Since there are no parameters to document, the description correctly avoids parameter details.

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 component registry' with a specific verb and resource. It enumerates the template types and explains what each entry contains, making it easy to distinguish from other sim_* tools. The mention of sim_compose further differentiates it as a discovery tool rather than a composition tool.

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

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

The description provides a clear usage hint by stating 'Compose them with sim_compose', indicating the typical workflow of listing then composing. It does not explicitly list when not to use this tool, but the context strongly implies it is for browsing available templates before composition.

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?

With annotations already indicating destructiveHint and openWorldHint, the description adds valuable context: the result is a new content-addressed model 'you own', lineage is recorded when composing onto an existing id, and attach fuses ports. It does not contradict annotations and expands on the operational 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?

Three sentences, each packed with useful information: core action, key parameter semantics, and a worked example. No fluff, front-loaded with the main purpose, and the example at the end reinforces usage without bloating.

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 params, no output schema), the description covers main usage patterns, attach mechanics, prefixes, and an example. It does not state the return value or error conditions, but the annotations and parameter schemas fill much of the gap, making this sufficiently 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?

Schema coverage is 100%, but the description adds operational semantics beyond the schema: 'omit id to start fresh', 'name kept from the base', attach maps port names to existing place ids, and prefix defaults to the component name. This meaningfully clarifies how parameters interact in the composition workflow.

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 (instantiate/compose) and resource (registry component into a model), and clarifies it stores a NEW content-addressed model with lineage. It distinguishes itself from siblings like sim_create_model or sim_extend by emphasizing 'registry component' and 'compose onto an existing id'.

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

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

The description provides clear when-to-use guidance: omit id to start fresh, pass attach to fuse a component port onto existing places, and uses a concrete three-call helpdesk example. It does not explicitly name alternative sibling tools or exclusions, but the context is strong.

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?

The description explicitly states the operation is read-only: 'WITHOUT rewriting its rates' and calls it 'the read sim_calibrate.' However, annotations declare readOnlyHint=false and destructiveHint=true, directly contradicting the described behavior. The description does add useful behavioral detail (per-trace diagnostics, one-case-at-a-time replay, lossy-encoding caveats), but the annotation contradiction is disqualifying under the rubric.

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 dense but every clause earns its place: purpose, alternative, metrics, diagnostics, log format, replay model, and a caveat are all included. It is somewhat run-on with multiple parentheticals, but it is front-loaded with the core purpose and read-only distinction, so it remains efficient for its 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 there is no output schema, the description does well to name the returned metrics and per-trace diagnostics that name activities that could not fire. It also explains the required log format and the modeling assumption (per-case workflow). It could go further by enumerating the specific lossy-encoding caveats, but overall it provides enough context 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?

With 100% schema coverage, the baseline is 3, and the description adds genuine value beyond the schema for the log parameter: it specifies exact CSV columns (case_id, activity, timestamp), the sim_dataset shape, and that activities are transition ids. The id parameter is simple and adequately covered by the schema as 'model 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 names a specific verb and resource: 'Check how well a stored model matches an observed event log' and immediately distinguishes itself from sim_calibrate by framing it as the read-only conformance component. It further lists concrete conformance metrics (fitness, precision, generalization, simplicity), so an agent can tell exactly what the tool evaluates.

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

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

The description explicitly positions this as 'the read sim_calibrate bundles into calibration, offered on its own,' giving a clear when-to-use signal versus the calibration sibling. It also gives concrete exclusion guidance: the log is replayed per-case from the initial marking, so a resource net with shared places 'will not fit.' An agent gets actionable selection criteria.

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 declare destructiveHint=true and openWorldHint=true. The description adds the crucial content-addressed behavior: reusing an existing name returns the existing id instead of creating a duplicate. This is a semantic nuance beyond the annotation flags. It also explains the design rationale for not storing mutable members, which helps an agent understand side effects. 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 main action and return value are front-loaded. The subsequent explanation about member lists and the analogy to Lineage is useful behavioral context, but it does add length. It is still efficient and each sentence contributes to understanding the tool's scope, so it earns a high score with a slight deduction for extra 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?

With a single parameter and no output schema, the tool's behavior is well covered: it describes the return (content id), how to interact with related tools (sim_link, sim_neighbors), and the content-addressed semantics that prevent surprising duplicates. It does not enumerate error conditions (e.g., invalid name format), but for a simple creation tool, the coverage is strong.

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

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

The only parameter 'name' has a schema description ('collection name'), but the tool description adds that the name is content-addressed — duplicates resolve to the existing id. This directly informs how to interpret the parameter value and its effect, exceeding what the schema alone conveys.

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 the exact action ('Mint a named Collection'), the return value ('return its content id'), and distinguishes this tool from siblings like sim_link and sim_neighbors by explicitly stating that it creates only and does not carry members. This leaves 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?

The description names the tools used for adding members (sim_link) and reading them (sim_neighbors, sim_edges), giving clear routing guidance. It does not explicitly state 'do not use for member management', but the separation of responsibilities is implied strongly. A minor gap is not specifying prerequisites or when to avoid this tool.

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 annotations' mutation flags, the description adds significant behavior: models are immutable, changed models produce a new id, malformed nets are rejected with every validation reason at once, and the model remains private until licensed. It also explains ownership and sharing implications, which annotations cannot 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 concise and front-loaded: core storage and identity behavior first, validation behavior second, and lifecycle/ownership context last. Every sentence earns its place, with no filler or repetition of the schema.

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?

Even without an output schema, the description covers what to pass, what is returned, immutability, validation behavior, privacy, and the relevant cleanup licensing/deletion alternatives. An agent has enough context to call the tool correctly and understand its side effects.

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 only says 'the model JSON', while the description specifies the required JSON keys (name/places/transitions/arcs) and mentions validation behavior. Since schema coverage is 100%, the description adds meaningful semantic detail without needing to compensate for missing parameter docs.

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 verb ('Store') and resource ('Petri-net model') and states the return value ('content id'). It further distinguishes the operation from lifecycle siblings by noting immutability and the one-id-per-model behavior.

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?

There is no explicit 'use this instead of X' statement, but the description gives clear lifecycle context: the model is private until dedicated via sim_license_model and can be removed with sim_delete_model. This helps an agent see how this tool fits among siblings, though it doesn't state exclusions outright.

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 carry readOnlyHint, destructiveHint, openWorldHint, and idempotentHint, so the description only needs to add context beyond them. It does: divergence is framed as a finding rather than an error, trust is defined as agreement between independent readings, and known limitations (small-count mean-field gaps, prior threat-blindness, gated nets with no ODE reading) are named. It does not elaborate on the destructive hint, but the annotations cover that.

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 dense but front-loaded with the core action, and every sentence adds a distinct piece of context: what readings are compared, how to interpret divergence, what trust means, and when readings do not apply. It is long, but the complexity of the tool justifies the length, and there is no 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?

For a complex comparison tool with no output schema, the description covers the main purpose, interpretation of results, key limitations, and a documentation pointer. The main gap is that it does not specify the exact response shape or what happens when no readings are applicable, but the description is otherwise sufficient for an agent to invoke the tool correctly.

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

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

The input schema already describes all three parameters (id, hours, realizations), with 100% schema description coverage, so the description need not repeat parameter syntax. It adds conceptual context about SSA runs and mean-field gaps, but it does not materially extend the meaning of the parameters beyond what the schema provides; baseline 3 applies.

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: it runs every applicable READING of a model against other readings and reports agreement or divergence. It explicitly enumerates the comparison types (SSA means vs mean-field solve, conservation laws vs simulated means, incidence ranking vs rollouts vs exact search), which distinguishes it from generic sim_compare or sim_verify.

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 applicability context, such as game-schema models and the gated-net exclusion, and points to docs/engine-selection.md for the decision procedure. However, it never names sibling tools or states when to choose sim_crosscheck over alternatives like sim_compare, sim_verify, or sim_invariants, so the guidance is implicit rather than explicit.

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?

The description adds useful behavioral traits beyond annotations: determinism ('same id, same seed, same bytes') and the return format ('Returns CSV'). Annotations already indicate readOnlyHint false and destructiveHint true, but the description does not explain the nature of the destructive side effect. It provides some added context but leaves side-effect clarity to 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 two short sentences that front-load the core purpose and then give determinism and output format. Every sentence contributes new information with no redundancy, making it appropriately sized for a tool with only three parameters.

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

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

The description covers what the tool generates, its source, output format, and determinism, which is adequate for a simple tool with fully documented parameters. However, with no output schema, the CSV structure and columns are not described, and the destructiveHint true is not elaborated in the description. An explicit note about side effects would make the definition more 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?

Schema description coverage is 100%, so all three parameters (id, seed, cases) are already documented in the input schema. The description reiterates the role of id and seed in determinism but does not add new semantic details for the cases parameter or the CSV content. Since the schema carries the parameter meaning, the description meets the baseline without substantial additional value.

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 ('Generate'), a resource ('synthetic event log from a stored model'), and a method ('seeded SSA playout; case-per-arrival'). This clearly distinguishes it from the many sim_* siblings by emphasizing deterministic synthetic data generation from a model. It also mentions the CSV output, making the tool's 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 no when-to-use or when-not-to-use guidance, and it does not reference any alternative sibling tools such as sim_scenario or sim_run_pipeline. The purpose implies use for generating synthetic event logs, but an agent cannot determine prerequisites, exclusions, or when a different sim tool would be more appropriate.

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 mark the tool as destructive, non-read-only, and non-idempotent. The description adds valuable context about ownership requirements and the irrevocability of dedicating a model to the commons, which helps agents avoid destructive mistakes.

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

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

Two concise, information-dense sentences. The main action is front-loaded, and the refusal conditions are compactly itemized without wasted words.

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

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

For a single-parameter destructive tool with annotations already declaring destructive behavior and a 100% schema-covered parameter, the description covers the essential usage boundary cases. It does not discuss post-deletion effects, but the destructive annotation and refusal conditions provide adequate 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?

The schema already fully describes the only parameter, 'id', as the model id to delete. The description's ownership and refusal language adds context but not additional parameter-level meaning, so the baseline of 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 states the specific operation ('Delete a model you created') and the resource (a model), clearly distinguishing it from create, get, or supersede tools. The ownership qualifier and refusal conditions make the purpose precise 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 gives clear context for when this tool applies and explicitly lists refusal conditions: curated catalog models, unowned models, and commons-dedicated models. It does not name sibling alternatives for those cases, but the guidance is still highly actionable.

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?

The description explicitly claims 'Pure read,' but the annotations declare readOnlyHint=false and destructiveHint=true, a direct contradiction. This makes the tool's side-effect profile unreliable and fails to disclose any write/destructive behavior the annotations imply.

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 dense paragraph, but it front-loads the purpose and packs a lot of necessary output detail into a compact list. It earns its length given the tool's complexity, though bullet formatting would improve readability.

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?

There is no output schema, so the description carries the burden of explaining return values, and it does so thoroughly: gates, ranked influences, parameter classes, structural readings, and correction options. It even directs to a docs resource. The main gap is reconciling the 'Pure read' claim with the destructive annotation, which is already covered under behavioral transparency.

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 covers 100% of the six parameters with descriptions, so the schema carries the parameter documentation burden. The description adds some context about realizations adapting and the report's realizations field, but does not need to compensate for schema gaps. Baseline 3 applies.

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—'Test a stored model without writing a fitness test for it'—and enumerates a detailed set of diagnostic outputs, from generic gates to structural readings. The purpose is unmistakable, though it does not explicitly name a sibling tool to distinguish itself from.

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?

Gives clear context: use this when you want a read-only diagnostic without authoring a fitness test, and explains that corrections happen via tagging or declaring simulation.objective. It also points to a docs resource for interpreting results. It does not name sibling alternatives or state explicit exclusions, but the use case is sufficiently clear.

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?

The description says it produces a 'readout' (a non-mutating report), but the annotations include destructiveHint=true. This is a contradiction: a readout implies no destruction, and the description does not mention any destructive side effects. No additional behavioral context is added 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 two sentences that are packed with specifics, no filler, and the core concept (structural difference) is front-loaded. The second sentence adds context about when it's useful.

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 no output schema, the description gives the categories of changes detected but does not describe the shape or format of the returned readout, nor does it address the destructive behavior indicated by annotations. For a diff tool, this leaves an agent uncertain about what response to expect and what side effects may occur.

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 provides full descriptions for both parameters (a: model id before; b: model id after), and the description adds the notion that these are ids in a lineage, which is a small semantic enhancement. But overall the schema already carries the meaning, so 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 it computes a structural difference between two stored models, listing specific categories of changes (places, transitions, arcs, numeric attribute changes). It connects to the lineage context of builder turns, sim_extend, and sim_refine, which helps distinguish from those tools. However, it doesn't explicitly differentiate from sim_compare, so there is some ambiguity among 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?

The description implies when to use it: when you need the readout of what a builder turn, sim_extend, or sim_refine changed between two ids in a lineage. But it doesn't provide explicit guidance on when not to use it or mention alternatives like sim_compare. The context is helpful but not prescriptive.

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 destructiveHint=true and openWorldHint=true, and the description does not contradict them. It adds meaningful behavioral context by warning that agreementBefore/agreementAfter should be read rather than the loss, and that zero improvement is a structural finding, not a failed fit. This goes beyond what annotations alone provide.

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 action is front-loaded, but the description becomes dense and jargon-heavy with phrases like 'petri-pilot experiments/ode-minimax' and a long conceptual aside. The guidance is valuable, but it could be tightened without losing meaning.

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 three parameters, no output schema, and annotations already covering safety and openness, the description covers the key points: what it does, how it differs from sim_calibrate, and how to interpret results. It mentions agreementBefore/agreementAfter as the relevant outputs. A concrete example of the groups JSON would improve completeness, but the schema already provides one.

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 three parameters. The description adds context around groups as transition groups sharing multipliers and positions being self-play-sampled and search-labeled, but it does not significantly elaborate on id or options beyond the schema. This meets the baseline but does not exceed 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: it distills exact search into the play scorer by fitting rate multipliers for named transition groups. It also clearly separates this from sim_calibrate by calling it the tactical counterpart. The purpose is unambiguous and actionable.

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 explicitly names the sibling alternative, sim_calibrate, and distinguishes it by data source: event log versus positions sampled by random self-play and labeled by search. The division of labor is described as deliberate, which tells an agent when to select this tool over the sibling. The caveat about zero agreement improvement also guides interpretation.

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?

The description says the tool only lists relations, implying a safe read operation, but the annotations mark readOnlyHint=false and destructiveHint=true. This is a direct annotation contradiction that makes the tool's actual side effects unclear and undermines the description's credibility.

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 with the core action front-loaded and the rationale in a second explanatory sentence. The tradeoff discussion is wordy but earns its place as performance guidance, so the length is reasonable.

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 single-parameter list operation, the description conveys the result scope and cost model well. However, it doesn't describe the shape of the returned relations, and the contradictory annotations prevent a complete picture of the tool's safety profile, so an agent cannot fully rely on this definition.

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 describes the single id parameter as 'entity id to look up' with 100% coverage. The description adds the context that the entity lives in a model graph, but that doesn't meaningfully extend the schema's parameter semantics, so the baseline of 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 opens with a specific verb and resource: 'List every relation touching an entity, as either subject or object.' It clearly differentiates the two-directional scope from the one-directional view datum_edges gives, so an agent can tell exactly what this tool returns.

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 useful context about when a scan is acceptable ('this is a simulation sandbox's model graph, not a large corpus') and explains the performance tradeoff of scanning over a maintained index. However, it doesn't explicitly name alternatives or state when not to use this tool over similarly named siblings like sim_neighbors.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the agent knows this is a mutating, non-idempotent operation. The description adds meaningful behavioral context beyond the annotations: it explains the two execution modes (continuous ODE relaxation vs exact seeded SSA rollouts), states that the response says which mode was used, and notes the schema dependency. It does not detail what gets destroyed or what side effects occur, but the annotations plus the mode disclosure cover the main behavioral risks.

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 dense but efficient: it front-loads the core algorithm, then covers schema requirements, engine selection, and the response's mode disclosure in three sentences. The parenthetical '(the tic-tac-toe blog technique)' is slightly informal but not wasteful. Every sentence earns its place, though the algorithm explanation could be tightened.

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 5 parameters, no output schema, and a complex algorithm, the description covers the essential context: what the tool computes, how it computes it, what schema it needs, and how the engine choice is determined. It does not describe the return value structure (though no output schema exists, so the description could have helped), nor does it explain what 'destructive' means in this context. Still, the description is substantially complete for an agent to decide whether to call it.

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 five parameters. The description adds context for 'marking' (sparse marking override, the position to evaluate from) and 'realizations' (SSA rollouts per elimination), which maps to the gated-net execution mode. However, it does not explain the semantics of 'horizon' beyond 'model time to explore ahead' or clarify how 'player' interacts with the elimination algorithm. Baseline 3 is appropriate because the schema carries the load and the description adds only modest extra 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 names a specific verb ('Score'), a specific resource ('a player's legal next moves'), and a precise method (NEXT-MOVE ELIMINATION) with a one-line explanation of the algorithm. It also distinguishes itself from the sibling sim_scenario by referencing the same engine-selection rule, so an agent can tell them apart.

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 clear context: it needs the game schema (simulation.objective + simulation.players), and it explains the engine choice rule (ungated vs gated nets) with a pointer to docs/engine-selection.md. It does not explicitly say 'use this instead of sim_scenario when...' but the engine-rule cross-reference and the focus on next-move elimination imply the intended use case.

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?

The description discloses validation before storage, refusal with reasons and nothing written on malformed nets, and the exact return payload (new id, applied ops, diff). This goes well beyond the annotations (which only hint at destructive potential) and adds no contradiction.

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

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

The description is front-loaded with the core purpose and then systematically lists operations, validation behavior, and return values. It is somewhat long due to the operation catalog, but every section earns its place and is logically ordered.

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 complex tool with a variable operations array and no output schema, the description covers invocation, exact operation shapes, validation, failure atomicity, and return values. An agent has everything needed to call it correctly without further reference.

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 enumerates each operation type and its required fields (add_place, add_transition, etc.), giving the operations parameter rich semantics far beyond the schema's generic 'JSON array of operations'. This significantly helps an agent construct valid input.

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 applies structural edits to a stored model and stores the result as a new owned model with lineage, which is a specific verb+resource+outcome. It enumerates the full operation vocabulary, distinguishing it from creation, comparison, and deletion tools in the sibling list.

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 strong context: edit a stored model, receive a new model, use the same operations as the guided builder. However, it does not explicitly name when not to use it or how it differs from siblings like sim_create_model or sim_supersede_model, so it falls short of full 5.

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?

The annotations declare readOnlyHint=false and destructiveHint=true, while the description says 'Fetch' — a read-only operation. This is a direct annotation contradiction that leaves the agent unable to trust whether the tool has 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 focused sentence with the verb and object front-loaded. The explanatory clause about recorded transforms earns its place by clarifying what will be returned.

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

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

For a simple one-parameter getter, the description covers the core resource and return content, but it does not address missing-id behavior, error cases, or return format. The annotation contradiction also leaves the side-effect profile ambiguous.

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 single 'id' parameter is documented as 'binding id.' The description adds only 'by id,' which repeats the schema and gives no extra format, constraint, or default context. 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 operation: 'Fetch a stored Binding by id,' and explains what a Binding is ('which model/port feeds which, and any recorded transform'). It does not explicitly distinguish itself from sim_list_bindings, but the intent is still 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?

There is no guidance on when to use this tool versus alternatives like sim_list_bindings or sim_get_model. The parenthetical 'see sim_bind' points to a related tool but does not explain selection criteria or exclusions.

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?

The description characterizes the operation as a read ('Fetch'), but annotations declare readOnlyHint=false and destructiveHint=true. This is a direct contradiction: the description claims a benign retrieval while the annotations signal destructive potential. The description does not explain the side effects or why the destructive hint is set.

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 filler. Every word contributes: the action, the resource, the return format, and the lookup key are all 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?

For a one-parameter tool, the description plus schema covers the basic invocation path and the return format. However, the contradictory destructive annotation is left unexplained and there is no output schema to compensate, so a fully confident call remains 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?

The input schema already fully describes the single 'id' parameter as 'model id (content hash)', so schema coverage is 100%. The description's 'by id' adds no additional parameter meaning; it only restates the relationship already documented 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 uses a specific verb ('Fetch'), a clear resource ('a stored model's full Petri-net JSON'), and the selection mechanism ('by id'). It clearly distinguishes what this tool returns from sibling tools like sim_list_models or sim_get_binding.

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 the tool is appropriate when you already have a model id and want its full Petri-net JSON, but it gives no explicit guidance about when to prefer it over alternatives or when not to use it. No exclusions or sibling comparisons are provided.

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?

The annotations mark destructiveHint=true and readOnlyHint=false, yet the description only presents a read-only-looking 'derive/computation' profile and never explains what side effect or destruction may occur. It does add useful semantic context about the absence of simulation and the universal claims, but the mutation/destructive behavior is undisclosed. This is not a direct contradiction because the description never claims to be side-effect-free.

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 longer than average but front-loads its main purpose and structures the three result families into clear clauses. The sim_diagnose clarification and the no-simulation caveat earn their place; mild verbosity in the first sentence keeps it from a perfect 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?

For a one-parameter tool with no output schema, it explains all three result families, their provenance from the arc structure, and the meaning of deadlock witnesses. That is enough for an agent to know what it will get back. The main gap is the unexplained destructiveHint, which leaves the overall invocation contract 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?

The schema already documents id with 100% coverage, so the description adds little about the parameter itself. It does reinforce that id refers to a model and adds meaningful context about 'this model's own initial marking', which helps an agent understand how the invariants are grounded.

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

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

The description uses a specific verb, 'Derive', and a precise resource, 'a model's full algebraic invariant structure', then enumerates three concrete output families: P-invariants, T-invariants, and the siphon/trap report. It also differentiates itself from sim_diagnose by explicitly saying this is the same computation, not a lesser copy, so an agent can distinguish it from 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 clear context: this is for static algebraic structure, explicitly excludes simulation, and points out the relationship to sim_diagnose's structural fields as an alternative access point. It stops short of a broader decision rule against simulation-oriented siblings, but the boundary is clear enough.

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 mark destructiveHint=true, and the description goes beyond this by explaining the irrevocable nature, the global visibility effect, and the safety rationale for others building on the model. This adds meaningful behavioral context about consequences that annotations alone do not 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 efficiently structured: main action first, then the key consequence (irrevocability), then practical licensing advice. Every sentence contributes value, and the warning is front-loaded in a way that helps an agent avoid misuse.

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 two-parameter operation with annotations covering read/write and destructive behavior, the description fully covers the purpose, side effects, permanence, and licensing nuance. There is no output schema, but the description's explanation of what happens after dedication is sufficient for an agent to invoke 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?

Schema coverage is 100%, but the description adds important semantic meaning beyond the schema by clarifying that the model must be one 'you created', which is not explicit in the schema's 'model id to dedicate'. It also reinforces the license options and provides guidance on choosing CC0, though it does not describe exact parameter syntax.

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 ('Dedicate a model you created to the commons'), the specific licenses accepted, and the observable effect (appears in every user's listing with the license shown). It is specific and distinct from sibling tools like sim_publish or sim_delete_model.

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 strong context for when to use the tool by emphasizing that the dedication is IRREVOCABLE and cannot be changed or deleted, signaling caution before use. It also gives licensing guidance (CC0 is the cleanest choice for models), though it does not explicitly name alternative tools or state when not to use it beyond the irreversibility warning.

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?

The description adds valuable behavior beyond annotations: there is no fixed predicate vocabulary, the edge can connect any stored entity, and exact duplicate storage returns the same id rather than creating a duplicate. Annotations already signal mutating/destructive behavior, and the description does not contradict them; it enriches them with deduplication semantics.

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 longer than average, but each sentence contributes: the core action, the open vocabulary, the distinction from Lineage, and the deduplication rule. It is front-loaded with the main action and remains structured enough to parse quickly.

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 three-parameter tool with clear annotations and complete schema coverage, the description covers the important context: what counts as a Relation, how it differs from Lineage, and what happens on duplicate storage. The absence of an output schema is partially mitigated by the mention of returning the same id; a brief note on the success response shape would make it fully 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?

Schema coverage is 100%, so the baseline is 3, but the description adds semantic meaning to the predicate parameter by emphasizing that it is caller-defined and giving examples like hasMember, cites, and supersedes. It also clarifies subject and object as endpoints of a typed edge between stored entities, which goes slightly beyond the schema's terse 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 and resource: 'Record a typed edge between any two stored entities.' It defines the tool's scope precisely (any content-id-addressed entity) and explicitly distinguishes Relations from Lineage and from sim_create_collection's membership edges, making it clear what this tool is for.

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 concrete guidance on when to use this tool versus Lineage: Lineage is for derivation, while Relations are for any other relationship assertion. It also references datum_link as a behavioral peer and mentions membership edges, giving an agent enough context to select the right tool, though it stops short of an explicit 'use X instead' list.

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?

The description says 'List', which is a read-only enumeration operation, but the annotations set readOnlyHint=false and destructiveHint=true, implying the tool may mutate or destroy data. This directly contradicts the description and nothing in the description reconciles the destructive hint.

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, front-loaded sentence with no filler. It communicates the operation, the resource, and the return value without redundancy.

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

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

For a zero-parameter list tool, the description adequately names what is returned. However, given the annotation-implied destructive behavior, it is incomplete and potentially misleading. There is also no output schema, so the brief description must carry more weight than it does.

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

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

The tool has zero parameters and the schema has 100% coverage since the schema is an empty object. The baseline of 4 applies because there are no parameter semantics the description needs to clarify.

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 names a specific verb ('List'), a specific resource ('stored Binding'), and the exact output ('content id'). The word 'every' signals exhaustive enumeration, which helps distinguish it from sim_get_binding, though it doesn't explicitly name any sibling alternative.

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

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

There is no guidance about when to use this tool versus alternatives such as sim_get_binding. No exclusions, prerequisites, or context are provided; the intended usage is only implicitly that it enumerates all stored bindings.

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?

The description describes a purely read-only listing operation, but the annotations declare readOnlyHint=false and destructiveHint=true. This directly contradicts the described behavior, so this dimension scores 1 and is flagged as an annotation 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?

Two dense sentences front-load the main action and resource, then add category boundaries and a practical cross-tool note. Every clause earns its place and there is no redundancy.

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

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

The description explains visibility boundaries well, but with no output schema it doesn't specify the exact response format, such as how 'mine' is marked or whether license information appears in the entry. This is adequate for a simple list tool but not fully 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?

There are zero parameters, so the baseline is 4. The description adds a helpful semantic about model IDs being usable across all sim_* tools, even though there is no input schema to document 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 starts with a specific verb and resource ('List the models visible to you') and then enumerates the exact categories included (curated catalog, commons, own). This clearly distinguishes the tool from model creation, retrieval, and deletion 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 a clear scope for when to use the tool: to enumerate visible models, including the fact that other users' undedicated models are excluded. It also adds a useful cross-tool note that any shared model ID works with sim_* tools. It does not explicitly name a sibling alternative, but the scoping is strong.

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 mark the tool as destructiveHint=true and readOnlyHint=false, directly contradicting the description's 'Fetch' behavior. Because the description conflicts with the annotations, an agent cannot trust whether the operation is actually a read or has destructive 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 sentence with no filler and the action is front-loaded. It is appropriately concise for a one-parameter lookup 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 description is too sparse relative to the annotations: it does not clarify the destructive behavior implied by destructiveHint=true, nor does it address not-found behavior or return shape in the absence of an output schema. An agent would not have enough coherent context to invoke the tool safely.

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 the id parameter, and the description only restates it as 'by id'. The description adds no extra semantic detail beyond what the input schema provides.

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 (Fetch), a resource (a stored Map's key->value data), and a selector (by id), so an agent can identify this as a single-map lookup. It is distinguishable from siblings like sim_map_list or sim_map_put, but it does not explicitly name those alternatives, so it misses 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?

No guidance is given about when to use sim_map_get instead of sim_map_list or sim_map_put, and there are no when-not-to-use conditions. The only clue is the phrase 'by id', which is more parameter semantics than guidance for tool selection.

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?

The annotations declare readOnlyHint=false and destructiveHint=true, yet the description only says 'List', which implies a safe, read-only operation. The description does not disclose any destructive side effects or mutation behavior, and it directly conflicts 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?

A single, front-loaded sentence states the action, resource, and output with no filler. Every word contributes to understanding the tool's 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?

The tool is simple and the return value is described, but the annotations indicate potentially destructive or non-read-only behavior that the description completely omits. An agent cannot safely invoke this tool without knowing those side effects, so the description is not contextually complete.

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

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

The tool has zero parameters, so no parameter documentation is required. The description clarifies that the result scope is 'every stored Map', which is sufficient context for the single available operation.

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

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

The description uses a specific verb, 'List', names the exact resource, 'stored Map', and the output, 'content id'. It is clearly distinct from sibling tools like sim_map_get, sim_map_put, sim_list_models, and sim_list_bindings.

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?

There is no guidance on when to use this tool versus alternatives such as sim_map_get or sim_map_put. The intended use case can be inferred from the description, but no explicit conditions, exclusions, or alternative comparisons are provided.

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 annotations, the description adds meaningful behavior: content-addressed identity, order-insensitive key insertion, and the fact that the return value is a content id. This enriches the agent's understanding without contradicting the provided annotation 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?

Two sentences with the core action front-loaded, followed by clarifying examples and the content-addressing identity behavior. Every clause earns its place; there is no 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?

For a one-parameter store operation, the description covers what is stored, what is returned (content id), and the deduplication behavior. Annotations cover side-effect hints, and no output schema is needed given the simple return value.

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 already documents the single data parameter as 'the table as a JSON object,' so the baseline is 3. The description adds semantic value by framing it as a key->value lookup table and giving concrete examples such as parameter sweeps, rate tables, and component registries.

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: 'Store a key->value lookup table as its own content-addressed entity.' It further distinguishes itself from free-text artifacts and Petri-net models, making its purpose unmistakable and differentiating it from sibling tools.

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

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

The description gives a clear decision rule: use this for anything shaped as key->value rather than free text or a Petri net. It doesn't explicitly name retrieval siblings like sim_map_get or sim_map_list, but for a store operation the context is sufficient.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, which is surprising for a 'List' operation and suggests the tool may have side effects or destructive behavior. The description does not explain this contradiction or disclose what destructive action might occur, nor does it clarify the 'openWorldHint' meaning. The description adds no behavioral context beyond the annotations and actually conflicts with the expected read-only nature of listing.

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 filler. Every word earns its place: it names the action, the resource, the scope ('this user'), and the output ('URLs').

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 parameterless tool with no output schema, the description is mostly complete in terms of what it returns. However, the annotations signal destructive behavior and an open world, which the description fails to address. An agent cannot tell whether calling this tool will mutate or delete published sheets, which is a critical gap for a tool that sounds read-only.

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

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

The tool has zero parameters, so the schema provides no parameter documentation. The description compensates by clearly stating the resource being listed and the output (URLs), which is sufficient for an agent to know what the tool operates on. Baseline 4 is appropriate for a parameterless tool.

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

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

The description states a specific verb ('List') and resource ('sheets this user has published'), and mentions URLs as the key output. It is clear enough to distinguish from most siblings, though it does not explicitly name a sibling alternative.

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

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

The description implies a read-only listing use case ('List the sheets this user has published'), which is clear context. However, it does not state when to use this tool versus alternatives like sim_list_models or sim_list_bindings, nor does it mention any exclusions or prerequisites.

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 declare destructiveHint=true and readOnlyHint=false, but the description does not explain what destructive side effects occur (e.g., does traversal mutate anything? does it create a temporary graph?). The openWorldHint=true is also not elaborated. The description adds the subject-direction and predicate-filter behavior, but the destructive nature is a significant unexplained 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?

Two sentences with no filler. The core behavior is front-loaded, the optional filter is stated, and the example is concrete. Every sentence earns its place.

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

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

The description is complete for a simple traversal tool, but the destructiveHint=true annotation raises a red flag that is not addressed. Without an output schema, the agent also doesn't know what the traversal returns (e.g., list of ids? objects?). The example helps, but the destructive behavior and return shape are 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 both parameters. The description adds the subject-direction meaning and the hasMember example, which is helpful but not extensive. 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 states a specific verb ('traverse') and resource ('one-hop... from an entity'), and clarifies the directionality ('where it is the subject'). It also gives a concrete example ('Pass a collection's id with predicate hasMember to list its members'), which distinguishes it from sibling tools like sim_edges and sim_link.

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 explains the core usage context: one-hop traversal from a subject, optional predicate filtering, and a concrete example. It does not explicitly name alternatives or exclusions, but the example and scope make the intended use clear.

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?

The description adds substantial behavior beyond the annotations: it discloses the Monte Carlo sampling method, the requirement for a continuous engine, the refusal behavior with a reason, and the Pareto-flag output. While it does not elaborate on what destructive side effects might occur (destructiveHint=true), annotations already flag that trait, so the description adds useful context 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?

Two focused sentences pack all critical information: the first sentence explains the method and output, the second states the limitation and redirects. No filler; every phrase 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?

For a complex tool with no output schema, the description adequately explains what is returned ('every sample with a Pareto flag', 'non-dominated set is the trade-off frontier') and when it fails. It could mention side effects or result format more fully, but it covers the essential operational and limitation aspects.

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 100% schema description coverage, the baseline is 3, but the description enriches the parameters by mapping 'transition rates' to the parameters JSON, 'served vs walked out' to objectives, and 'Monte Carlo samples'/'horizon' to samples/hours. This gives the agent domain-level understanding beyond the schema field names.

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 resource ('transition rates for a stored model') and a specific algorithm ('Multi-objective optimisation', 'Monte Carlo samples', 'Pareto flag'), and it explicitly names a sibling tool (sim_compare) when the model has a schedule or gate. This differentiates it clearly from other sim_* 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 an explicit exclusion condition ('a model with a schedule or a gate is refused') and directly points to the alternative ('use sim_compare with explicit scenarios for those'). This is precise when-to-use / when-not-to-use guidance that an agent can act on.

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?

It adds meaningful context beyond annotations by disclosing the continuous-engine requirement and refusal behavior. However, annotations mark the tool destructiveHint=true, and the description does not explain what gets destroyed or what side effects a run has; with that strong annotation, more disclosure would be expected.

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

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

Two tight sentences: the first front-loads the core operation and output shape, the second states a key limitation. No filler or repetition of schema content.

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 an 8-parameter tool without an output schema, the description covers the operation, output as a grid, and a critical refusal case. It could clarify what destructiveHint=true means in practice, but the agent can otherwise call the tool correctly using the schema.

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 carries the parameter burden. The description reinforces that param_x/param_y are transition rates and observable fills the grid, but adds no format or edge-case details beyond what the schema already states.

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 ('Two-rate grid for a stored model') and specifies the exact mechanics: vary two transition rates, run each combination, return final observable value as a grid. This clearly distinguishes it from siblings like sim_scenario or sim_optimize even without opening their schemas.

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 intended use case ('which regime of arrivals × restock keeps the queue empty') and a clear exclusion: models with a schedule or gate are refused with the reason. It stops short of naming alternative tools for those cases, but the refusal condition is explicit.

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?

The description is exceptionally transparent. It discloses parent lookup order, context labelling, content-addressed prompt storage, lineage placement, the Relation{prompt, 'produced', result}, conditional storage as model vs artifact, and refusal without a provider. These details go far 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 first sentence front-loads the purpose, and every subsequent sentence adds a distinct, non-redundant behavioral fact. The paragraph is long because the behavior is genuinely complex, but the density is justified.

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

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

The description covers input handling, processing, storage, lineage, relation creation, and the no-provider failure mode. The only notable gap is that it does not state the caller-facing return payload, though stored side effects are emphasized thoroughly.

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 already covers all three parameters, so the baseline is 3. The description adds real meaning to 'parent' by specifying the resolution order and to 'text' as the natural-language derivation request, moving it above baseline.

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 concrete verb and resource: 'Ask an LLM to derive something from a stored entity,' and names the entity kinds. It is clear about what the tool does, but it does not explicitly contrast the tool with sibling tools such as sim_reroll or sim_classify.

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 intended context is clear: run a prompt against a stored model, prompt, artifact, or map, with the parent's JSON supplied as context. It also notes a refusal condition when no LLM provider is configured. However, it does not state when to use this tool over alternatives or list exclusions.

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?

The description says "Pure read; nothing here is written to any model," while the annotations declare readOnlyHint=false and destructiveHint=true. That is a direct contradiction, so per rubric the score is 1. The description otherwise does disclose cost caps and assumption-grade output, but the annotation conflict is disqualifying.

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 text is long but information-dense: every clause earns its place by adding a constraint, cost, grading caveat, or next action. The opening sentence is a run-on with em-dashes and comma splices, which costs a point on structure, but there is no padding.

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

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

The description covers the main operational concerns: source of Diagnosis, assumption-grade results, how to apply them, default catalog scan, and cost controls. However, it never describes the shape of the returned proposals, and the phrase "Costs one Diagnose run per model" sits awkwardly against "only from an existing measurement it reuses," leaving the execution mechanism ambiguous. The contradictory annotations also prevent the overall profile from being fully coherent.

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. The description mostly restates what the schema already says about ids, limit, and realizations; its only additive value is explaining that both caps exist because each model costs a Diagnose run.

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 object — proposing candidate @type values for stored models — and gives concrete examples ("QueueingSystem", "ResourcePool"). It distinguishes itself from a fresh-simulation classification path and explicitly names sim_link as the application step, so an agent can tell it apart from siblings like sim_classify.

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 states the prerequisite (the model's own Diagnosis), the exclusion (no fresh simulation run for classification), and the follow-up action (apply with sim_link; no separate apply tool). It does not explicitly name sibling alternatives for when this tool should NOT be used, but the conditions are clear enough to route correctly.

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 destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=true. The description adds valuable behavioral context beyond those: it mentions the daily quota, the refusal tab when the model is not honest, and that it returns the sheet URL. It does not detail side effects like overwriting an existing sheet or permission requirements, but the quota and refusal-tab details are meaningful additions. 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?

Three sentences, each earning its place: the first states the action and output contents, the second states the return value, the third states the quota constraint. The most important information is front-loaded. No filler or repetition of schema details.

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 publish operation with no output schema, the description covers the key return value (sheet URL), the main side effect (quota consumption), and the content of the output. It does not mention whether the operation overwrites an existing sheet or how the refusal tab is triggered, but the annotations already signal destructiveness and open-world behavior. The description is reasonably complete for an agent to decide to call it.

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 both parameters ('id' and 'scenario'). The description adds context for 'scenario' by saying it is 'a server-run scenario as data tabs', which clarifies the purpose of the scenario parameter. However, it doesn't add format or syntax details beyond the schema. 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 states a specific verb ('Publish'), a specific resource ('a stored model'), and a concrete destination ('the signed-in user's Google Sheets'). It also enumerates what gets published (model workbook, scenario data tabs, charts) and distinguishes itself from siblings like sim_publish_app and sim_publish_compare by naming the target and content. This is a clear, specific purpose statement.

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

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

The description implies when to use this tool: when you need to publish a stored model to Google Sheets with live formulas, scenario data, and charts. It does not explicitly name alternatives or exclusions, but the sibling list includes sim_publish_app and sim_publish_compare, and the description's specificity about Google Sheets and the model workbook helps an agent infer the distinction. It lacks an explicit 'use X instead when...' statement, so it falls short of a 5.

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

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

Beyond the annotations, the description discloses key behavioral constraints: the app runs in a sandboxed opaque origin with no cookies/session, only the CORS-open public API is reachable, root-relative imports are allowed while off-origin ones are refused, and the checks reject empty, oversized, model-id-less, or externally-dependent apps. It also clarifies that behavioral correctness is not verified by this tool. 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 description is dense but every sentence adds operational value: purpose, serving context, runtime template, component composition, import rules, and validation checks. It is front-loaded with the core purpose and then builds out practical constraints without 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?

For a publish operation with no output schema, the description covers the full call context: what is published, where it is served, how to construct valid HTML, what checks will reject it, and what the tool does not verify. Nothing critical for an agent to invoke 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?

Although the schema already covers both parameters at 100%, the description adds significant meaning: 'id' must be a model you own, and 'html' must be the complete self-contained document produced from the generator, with explicit import rules and composition guidance. This goes well beyond the schema's short field 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 states a specific verb ('Publish'), a specific resource (the generated single-file HTML app for a model you own), and the serving location (/app/<id>). It clearly differentiates this from generic publishing or model-management tools by tying it to the generator output and the model's view prompt.

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 strong guidance on how to use it: start from /lib/app-template.html, compose the listed components, keep imports root-relative, and satisfy the stated checks. It does not explicitly name alternatives or when not to use this tool, but the context is clear enough for an agent to know when this is the right publish path.

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 declare readOnlyHint=false and destructiveHint=true, and the description substantiates those by describing the write into the user's Sheets. It adds context annotations do not carry: the shared-seed execution guarantee ('differences are the scenarios and not the dice'), the exact artifacts produced (comparison table plus trajectory chart vs. data tabs), and the daily publish quota. 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?

Four sentences with zero filler. The core purpose is front-loaded in sentence one, differentiation in sentence two, behavioral detail in sentence three, and return value plus quota in sentence four. Every sentence earns its place.

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

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

For a 2-parameter tool with fully documented schema and no output schema, the description covers everything needed to call it correctly: the return value (sheet URL), side effects, quota implications, and the seed-sharing behavior that affects how the output should be interpreted. Nothing an agent needs 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% — both id and scenarios carry descriptions, with scenarios including a concrete JSON example. The description adds no parameter-specific syntax or format guidance beyond the schema, so the baseline 3 applies; the seed-sharing note is behavioral context rather than parameter semantics.

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

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

The description opens with a specific verb and resource: 'Publish a multi-scenario comparison into the signed-in user's Google Sheets.' It then explicitly positions itself against siblings ('sim_compare's export, the counterpart of sim_publish for a single scenario'), so an agent can distinguish it from both sim_publish and sim_compare without opening their schemas.

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 names sim_publish as the single-scenario alternative, giving the agent an explicit routing condition: multi-scenario comparisons go here, single scenarios go to sim_publish. It also ties itself to sim_compare's shared-seed semantics, clarifying the relationship between the analysis tool and its export.

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 provide readOnly/destructive hints, while the description adds context beyond them: the returned receipt's cryptographic content, two verification paths, the no-auth verification endpoint, and the current-signing-key endpoint. It does not detail side effects despite destructiveHint=true, but it adds substantial behavior beyond the annotation set.

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 most important behavior is front-loaded in the first sentence, followed by verification mechanics and the key endpoint. It is dense but not padded, though the final trust-ladder sentence is somewhat illustrative rather than strictly 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?

For a tool with no output schema and two parameters, the description covers the run behavior, the receipt format, verification methods, and a key retrieval endpoint. The only notable omission is an explicit response shape, but an agent has enough to select and invoke 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?

Schema coverage is 100%, so the baseline is 3, but the description enriches the scenario parameter by linking its shape to sim_scenario, noting defaults apply, and explaining that summary:true certifies the summarized form because the result hash covers the returned result.

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: 'Run a seeded scenario and get back the result PLUS a signed run receipt', and then defines what the receipt is (an Ed25519 certificate over model id, scenario, result hash, service revision). This clearly separates it from scenario-running siblings like sim_scenario.

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 explains how the receipt can be verified and calls reproducibility 'the bottom rung of the trust ladder receipts build', which implies a use case but never explicitly states when to choose this tool over sim_scenario or other sim_* siblings. No when-not or alternative-selection guidance is given.

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?

The description says 'Returns a NEW model id (ids are content addresses, so the original stays reachable)', implying a non-destructive operation. However, the annotations declare destructiveHint: true, directly contradicting that statement. This is a serious inconsistency for an agent deciding whether the call might destroy data.

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 dense but front-loaded: the core purpose and return value come first, followed by behavioral notes and a pointer to documentation. Every sentence contributes information; there is no filler, though the length is at the upper edge for a tool of 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 5 parameters, no output schema, and the provided annotations, the description covers the main behaviors (new id, diff, asymmetry of levers, signature handling). It omits explicit error conditions or prerequisites, but it is largely sufficient. The destructive contradiction slightly reduces completeness because the agent cannot trust the safety profile.

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 already covers all 5 parameters (100% coverage), so the baseline is 3. The description adds meaningful detail: for 'tags' it clarifies that only refine.-prefixed keys refine and that both places and transitions work; for 'signature' it states that unverifiable signatures are refused rather than stored. These enrich the schema without being redundant.

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 ('Refine'), a clear resource ('a model's parameter classes'), and the mechanism (editing tags or assertedClasses), then says it re-derives and returns a new model id plus a diff. It is unambiguous and distinct from siblings like sim_classify or sim_calibrate, even without naming them.

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 explains the two levers ('tags can only split classes; assertedClasses declares a merge') and instructs the user to read sim://docs/classification for why they are asymmetric. This gives implicit guidance on when to use each, but it does not explicitly state when to prefer this tool over alternatives 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.

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

The description goes well beyond annotations by detailing side effects (stores a new prompt and result, leaves original untouched), the reproducibility field and its conditions, and the lineage semantics. It does not contradict any annotation and adds substantial behavioral context, which is critical for a tool with destructiveHint=true and no output schema.

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 dense paragraph with many technical details (lineage, reproducibility, sim_edges/sim_neighbors). It is not poorly written but lacks structure; it could benefit from bullet points or clear separation of concepts. It is comprehensive but slightly verbose for a 3-parameter 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 description covers the core behavior, side effects, override rules, and the reproducibility check, which is the key output detail. Given there is no output schema, it explains the main return nuance but does not fully specify the entire response shape. It also references how to query results via sim_edges/sim_neighbors, which adds context. Overall very complete for a tool with this 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?

Schema description coverage is 100%, so each parameter (text, prompt, system) is already documented with override behavior. The description restates the default reuse ('Reuses the original prompt's text and system unless you override them here') but adds no new meaning beyond what the schema provides. The prompt parameter's role as an id is also clear in the schema. Baseline 3 applies.

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 re-runs a stored sim_prompt against the same parent, and explicitly distinguishes it from a chain by explaining it never derives from previous output. It names the resource (stored prompt) and the action (re-run), and the sibling contrast is implicit but strong.

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 explains when to use it: to re-run a stored prompt against the same parent, and clarifies the lineage behavior (siblings not chain). It also notes overrides and when reproducibility is checked. However, it does not explicitly mention alternatives like sim_prompt for new prompts, but the context implies the distinction.

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?

The description goes well beyond annotations by disclosing concrete runtime behavior: refusal of cyclic binding sets, rejection of invalid port directions, the timing of validation, the explicit seam assumption about fitness gates, and the cost of one Diagnose-shaped run per model. These details add operational context that readOnlyHint, destructiveHint, and idempotentHint cannot 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 dense but each sentence carries unique operational information: composition semantics, validation rules, timing, assumptions, and cost. It is front-loaded with the core action and avoids filler or repetition.

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 pipeline-execution tool, the description covers purpose, constraints, validation behavior, and cost, which is enough to select and invoke it correctly. It is slightly incomplete because there is no output schema and the return-value shape is only hinted at by the mention that the result carries an explicit seam assumption.

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 parameters—seed, hours, bindingIds, realizations—are already well documented in the schema. The description mostly reiterates schema wording, such as shared seed/horizon and automatic inclusion of touched models, without adding substantial new parameter-level meaning beyond the structured definitions.

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: 'Run a set of stored Bindings (see sim_bind) as a composed pipeline.' It further explains the mechanics—topological order and trajectory resampling—so an agent can distinguish this from other sim_* tools. Referencing sim_bind and sim_compare strengthens differentiation from 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?

The description provides clear context for when this tool is appropriate: after bindings are stored via sim_bind, and when composing models under the same discipline sim_compare enforces within one model. It also explains that port validation happens here, not at sim_bind time. However, it does not explicitly state when not to use it or name a direct alternative.

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 mark readOnlyHint=false and destructiveHint=true, while the description opens with 'Pure read — asking cannot change the model.' This is a direct contradiction and forces a 1 regardless of the rich behavioral detail elsewhere about engine refusal, schedule precedence, and summary key omission. An agent cannot safely trust whether invoking this tool is side-effect free.

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 the core action and returns, then organized into parameter and engine semantics. It is long but most sentences earn their place; a few phrases, like 'Forecast's caveats name which,' are slightly unclear and the engine-selection paragraph is dense.

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 no output schema, the description carries the burden of explaining return values and does so: trajectory, final marking, metrics, contention, caveats, assumptions, and the summary variant. However, it leaves some scenario keys like 'realizations' unexplained and defers part of engine selection to an external doc, which is a minor gap for such a complex tool.

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

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

The schema already covers id and scenario, with a full example JSON, so baseline is 3. The description goes well beyond this by explaining the semantics of 'samples' (sizes the answer, not the run), 'summary' (keys absent, not null), 'engine' choices, and how schedule/rate overrides interact with model-declared schedules. This adds substantial meaning beyond 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 first sentence names a specific action and resource: 'Run a seeded what-if scenario against a stored model,' and enumerates the kinds of overrides it applies. It is clearly distinguishable from the many sibling sim_* tools, and it even names sim_crosscheck as the alternative for running both engine readings side by side.

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 routing guidance: when to use 'ssa' vs 'ode', refusal cases for 'ode', and when to use 'summary': true when nothing will be plotted. It also points to docs/engine-selection.md for the full decision rule and suggests sim_crosscheck for side-by-side comparison, so when-to-use is fully specified.

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 annotations, the description discloses important behavioral details: the old id continues to work, any commons dedication remains valid, and only the listing moves to the successor. It also adds an ownership requirement. This significantly clarifies the side effects of the operation.

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

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

Three concise sentences with no redundancy. The core action is front-loaded, and every sentence contributes either to the operation's effect or its constraints.

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 two-parameter action with no output schema, the description covers the essential invocation requirements: what the operation does, the ownership prerequisite, and the behavioral effects. Nothing necessary for correct use 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 schema already defines each parameter clearly. The description adds meaningful context by explaining the relationship between old and new, the fact that the old id remains active, and the ownership requirement, which goes beyond the raw schema definitions.

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

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

The description uses a specific verb ('Mark an old version... as replaced by a newer one') and a clear resource ('model'), and it distinguishes the operation from siblings like delete_model or create_model by explaining the effect on listing while the old id keeps working. This makes the tool's purpose immediately identifiable.

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

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

The description clearly indicates when to use the tool: when replacing an old model version with a newer one, and it provides a key prerequisite ('Both models must be yours'). It does not explicitly name alternative tools or when not to use it, but the context is strong enough to guide selection.

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?

The description goes beyond the annotations by explaining the verdict types (proved/refuted/unknown), the soundness semantics of each method (structural/exhaustive/partial), and the caveats. It clarifies that 'unknown is never a pass' and that partial results are only sound for refutations. The annotations declare destructiveHint=true, and the description does not contradict this; it adds meaningful behavioral context about the verification guarantees.

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 dense but well-structured: it front-loads the core purpose, then explains verdict semantics, then method soundness, then caveats. Every sentence adds information. It could be slightly more concise, but the density is justified given the complexity of the verification semantics.

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 verification tool with no output schema, the description does a good job explaining what the agent should expect: verdicts, methods, and caveats. It doesn't describe the exact response format, but the verdict/method/caveat structure is implied. The annotations cover the safety profile (destructiveHint=true), and the description covers the semantic guarantees. Minor gap: no explicit statement about what happens on invalid input or how to interpret the 'id' parameter beyond 'model id'.

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 both parameters. The description adds context about what 'properties' means (the property kinds) and the default (bounded + deadlock-free), which is useful. However, it doesn't add syntax details beyond the schema's example, so the 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 states a specific verb ('verify') and resource ('declared properties of a stored model'), and enumerates the property kinds it handles. It distinguishes itself from siblings like sim_invariants and sim_diagnose by naming the exact property classes and verdict semantics.

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

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

The description clearly explains when to use the tool: to verify declared properties of a model. It does not explicitly name alternative tools for other verification tasks, but it provides enough context about the property kinds and verdict semantics that an agent can infer when this tool is appropriate. The caveats section also signals when results may be incomplete.

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