whatif

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

Goes far beyond the annotations: it enumerates every precondition (edge touches model, is offered, passes sim_link's check, ownership or authorship, target predicate's write rule), states atomic validation (all edges checked before anything is written; one failure writes nothing), describes partial-failure reporting, confirms the old edge survives, explains attribution/timestamps and migratedFrom provenance, and documents OAuth write scope, MCP-only availability, and the 1-compute-token cost. destructiveHint/openWorldHint give almost no detail on their own, so the description carries the load well.

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?

One dense paragraph, front-loaded with purpose followed by preconditions, then write semantics, idempotency, partial failure, auth and cost. Every sentence conveys distinct information, though the packing is heavy enough that a reader must hold several clauses at once.

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 still covers return-relevant behavior: attribution to the caller, existing: true for reused links, migratedFrom provenance edges, and what a partially completed call reports. Auth, availability and cost are all stated, so nothing needed 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema field text: the 1–25 bound's source, that edges must touch model, be offered, and satisfy sim_link plus the predicate's write rule for the caller, and that successor is validated against the currently returned successor (a re-point or extended chain is refused rather than followed).

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 verb and resource — carry a superseded model's offered taxonomic edges forward to its current successor — and names the exact upstream source (sim_migration_offers(model)) and the successor argument that selects the target. An agent can distinguish this from sim_link (creating new edges) and sim_supersede_model (creating the successor) without opening any schema.

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?

Makes the trigger clear: edges must be ones sim_migration_offers(model) offered, and successor must be the current one it returned, otherwise the call is refused. It also points to sim_edges and sim_query for verifying the result. It stops short of explicitly naming an alternative tool for the case where you want a different migration shape, so it is clear context rather than full when/when-not routing.

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?

Without relying on the schema, it discloses cost (1 compute token), refusal semantics ('a refusal stores nothing'), and exactly what edges get stored (binding->fromModel 'from', etc.). It broadly matches the annotations (destructive, not read-only), but 'storing the same binding twice returns the same id' reads as de-facto idempotent while the annotation sets idempotentHint=false, a mild tension rather than a flat 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 purpose is front-loaded in the first clause, but the body is a very dense wall of parenthetical validation clauses, several of which duplicate parameter-schema text (conversion triples, transform semantics, delay range). Much of the volume does not earn its place against the 100%-covered 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?

For a complex 9-parameter mutation tool with no output schema, the description is thorough: validation rules, conversion requirements, delay behavior, what is returned (same id on re-store), refusal behavior, and cost are all covered, so an agent has enough to invoke 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?

With schema description coverage at 100%, the schema already documents all nine parameters in detail (delay, transform, convertFactor, etc.). The description largely restates those same rules for unit conversions, transform scaling and delay, adding little syntax or meaning beyond the structured fields.

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 verb and resource: it records a checked connection between two models' declared ports as a content-addressed Binding. It also distinguishes scope from siblings by assigning set-level checks to sim_run_pipeline and sim_create_system, and self-loops to sim_extend.

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 routes several boundary cases explicitly (set-level checks belong to sim_run_pipeline/sim_create_system; a self-binding is refused and loops inside one net are built with sim_extend), and explains when a refusal occurs. However, it never addresses the obvious alternative sim_link or states a plain 'use this when' condition for the primary record-a-connection 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?

With annotations covering safety profile, the description goes far beyond them: it discloses the cost (3 tokens split 2 for replay + 1 for stored model), the exact shape of the returned evidence (rateEvidence with n, gapCV, insufficient flags), edge behavior at n=0 and n=1, the caveat emitted when gapCV suggests non-exponential timings, and why instant-pickup transitions are excluded. This is unusually rich operational disclosure for a mutation tool.

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

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

The purpose and cost are front-loaded, but the body is one dense paragraph that packs in evidence-field semantics, edge cases, and caveat mechanics without structural breaks. All of it is relevant, but the sheer length makes it harder to scan than a shorter, sectioned statement would be.

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 full burden of explaining return values, and it does: the new model, the learned rates/delays placement, lineage, and the conformance report fields (fittingPercent, worst traces, tokenFitness, rateEvidence). Nothing an agent needs to interpret results 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%, so the baseline is 3, but the description adds real semantics the schema lacks: the log parameter must be CSV text with columns case_id, activity, timestamp, activities are transition ids, and the id names the model to calibrate. The CSV column contract is essential invocation knowledge not present 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?

States a specific verb+resource (calibrate a model against an event log) plus the exact artifact consumed (CSV with case_id, activity, timestamp as emitted by sim_dataset). It distinguishes itself from siblings by tying its output to a NEW content-addressed model plus a conformance report, so an agent can separate it from sim_conformance or 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?

Gives clear context for invocation (upload a log of the sim_dataset shape) and a conditional routing cue ('read fittingPercent, not tokenFitness, unless you specifically want the raw-token number'), plus the precondition that fittingPercent should be checked before trusting learned values. It never names a concrete alternative tool for the no-learning case, so it stops short of a full when/when-not statement.

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?

Extraordinarily rich disclosure beyond the annotations: the 1,000,000-step budget, refusal-as-tool-error instead of silent fallback, cost of 1 compute token, and the meaning of the returned orbits/generator count (zero generators = rigid). The only gap is that it never reconciles the purely computational GET semantics it describes with the sibling annotations declaring destructiveHint=true and readOnlyHint=false, leaving the agent to guess whether hidden mutation occurs.

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?

Front-loaded with the core definition in the first clause, and nearly every sentence carries new information (orbits, budget, cost, witness path). It is dense and somewhat long-winded, with mild repetition around 'this is the id to compare, not the model id', but no filler sentences.

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

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

With no output schema, the description takes on the burden of explaining returns and does so: the canonicalId, the non-trivial automorphism orbits, and the generator count, plus the error condition. An agent has everything needed to call it and interpret the result.

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 real meaning by clarifying which identifier this is (a model id, explicitly not the content-addressed id and not the canonical id to compare against), which resolves a genuine ambiguity in the single 'id' parameter.

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 precise verb+resource: it computes an isomorphism-invariant canonical id from exact automorphism orbits. It explicitly distinguishes itself from the colour-refinement (WL) approach of sim_classify and from content-addressed ids returned by sim_get_model, so an agent can tell it apart from siblings 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?

Gives explicit routing: 'this is the id to compare, not the model id, when checking whether a catalog already holds this net', names sim_classify's fallback as the alternative for classification, and points to sim_prove for the actual bijection/witness. When-to-use and when-to-use-something-else are both covered.

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: it discloses that verify costs simulation, that the exact search refuses past a 1,000,000 refinement-step budget on large/symmetric nets, and that it falls back to a sampled permutation experiment. The one gap is that destructiveHint=true is never explained — nothing says what is mutated or destroyed (presumably the annotation slots), so the safety profile is left to the annotations alone.

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?

Front-loaded with the core action and return shape, and every clause carries information (annotation slot scope, verify behavior, budget, caveat pointer). It is dense and parenthetical-heavy, which slows parsing slightly, but there is little outright waste.

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

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

For a tool with no output schema and three parameters, the description covers what is returned (JSON-LD with empty annotation slots), the mutation contract ('nothing else'), and where to find the full colour-refinement caveat and annotation contract. It is nearly complete; only the destructiveHint implication is left implicit.

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 genuinely enriches verify beyond the schema by explaining the exact-proof vs sampled-experiment distinction and the budget cutoff. inline_context and id merely restate what the schema already documents in detail.

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

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

States a specific verb+resource: 'Discover the parameter classes of a stored model and return them as JSON-LD with empty annotation slots.' It also clarifies what the tool does NOT do ('membership/kind/evidence are derived and settled by measurement, not yours to edit'). It never names a sibling tool to differentiate itself, so it stops short of 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?

It gives conditional guidance for verify=true (exact proof where the search can decide, sampled experiment as fallback) and points to a resource for the annotation contract. However, it never states when to use this tool versus siblings like sim_propose_types or sim_param_heatmap, and offers no exclusions. Usage is implied rather than spelled out.

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?

Goes well beyond the annotations: discloses that sign-in with write scope is required (OAuth opens on first use), that it costs 1 compute token, that only the owner may add members because hasMember's write rule is subject-owner, that edges are immutable and members cannot be removed, and that name+account deterministically form the content id. Minor tension with idempotentHint=false (same name returns the existing id), but the description reads as the more specific statement of identity semantics rather than an inversion of the annotation.

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

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

Front-loaded with the core action and its return value, and most sentences carry operational facts (auth, cost, write rule, immutability). Slightly overwritten for a one-parameter tool — the 'Lineage lives beside a model' analogy is a digression that does not help invocation.

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

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

No output schema exists, and the description supplies the return value (content id) plus auth, cost, ownership enforcement, immutability and legacy-collection edge cases. An agent has everything needed to call it correctly on the first attempt.

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 the single 'name' parameter, so the baseline is 3. The description adds real meaning beyond the schema: name combined with account forms the content id, duplicate names return the existing id, and another account's identically-named collection is a distinct entity.

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?

Opening sentence states a specific verb+resource+outcome: 'Mint a named Collection you own and return its content id.' It is immediately distinguishable from siblings sim_link, sim_neighbors and sim_edges, which are named as the member-manipulation/read tools rather than the create 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?

Explicitly routes the agent: add members via sim_link(collectionID, "hasMember", memberID), read them back via sim_neighbors or sim_edges, and create your own collection when you encounter a pre-ownership legacy collection whose membership is frozen. Alternatives and the conditions selecting them are spelled out.

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 readOnly=false, destructive=true, idempotent=false, and openWorld=true, but the description adds substantial context: it writes one System, needs sign-in with OAuth the first time, costs 2 compute tokens, snapshots collections, enforces caps, applies binding checks, and explains determinism of the id. These are meaningful behavioral traits beyond the annotation layer.

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

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

The description is extremely long and dense, with nested clauses and tangential query examples that are not necessary for selecting or invoking sim_create_system. While the opening sentence is front-loaded, the remainder reads as an unstructured wall of constraints and sibling behavior rather than a concise tool definition.

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 creation tool with four parameters, no output schema, and rich annotations, the description is complete enough to call correctly: it covers inputs, mutual exclusivity, id determinism, stored checks, loop constraints, auth, cost, and what is returned. No critical invocation detail is missing.

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

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

Schema description coverage is 100%, so the baseline would be 3, but the description adds important semantics not in the schema: collection and models/bindings are mutually exclusive, collection snapshots members and affects the id, explicit lists and snapshots of the same ids are different systems, and size limits apply. It stops short of fully documenting every edge case in the parameter text.

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 defines a System as a content-addressed, stored set of models and bindings so the catalog can answer questions about them together. It also distinguishes the tool from closely related siblings such as sim_refine, sim_prove, sim_query, sim_bind, and sim_run_pipeline, so an agent can tell what this tool is for without opening another schema.

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

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

It gives explicit when/when-not guidance: pass either collection or models and bindings, not both. It also names alternatives for related questions (use sim_query for containment or refinement queries; use sim_prove for pair proofs) and clarifies where loop refusal happens versus where it is not consulted, leaving little ambiguity about routing.

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 real behavioral context beyond the annotations: divergence is framed as a finding rather than an error, mean-field gaps and threat-blindness are named, and the gated-net exception is disclosed. It does not, however, reconcile or explain the heavy side of the annotation profile (destructiveHint=true, openWorldHint=true, non-idempotent) for what reads as an analytical report tool, and says nothing about the compute cost of the SSA realizations it runs.

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?

Purpose is front-loaded in the first clause, and every subsequent sentence carries distinct information (the enumerated readings, the divergence policy, the gated-net exclusion, the docs pointer). The dense em-dash parentheticals make it heavier than necessary but not wasteful.

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 partially compensates by naming what is reported (agreement or divergence plus reason), which is valuable. It still leaves the agent without an idea of response shape, runtime, or why a cross-check tool carries destructive/open-world hints, leaving gaps for a tool with three parameters and non-read-only annotations.

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 all three parameters (id, hours, realizations) carry descriptions with defaults and maxima, so the schema does the heavy lifting. The description adds no parameter-level meaning, such as how hours interacts with the comparison or what realizations imply for result stability, making the baseline 3 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?

States a specific verb and resource: runs every applicable 'reading' of a model against the others and reports agreement or divergence, enumerating the concrete comparisons (discrete SSA vs mean-field, conservation laws vs simulated means, incidence ranking vs rollouts vs search). This is a distinct capability an agent can separate from sim_verify or sim_conformance, though it never explicitly names a sibling to route against.

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

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

Usage is implied through the applicability rules: gated nets have no ODE reading, and readers are pointed at docs/engine-selection.md for the four-rule decision. However, there is no explicit 'use this instead of X when Y' statement, nor a clear precondition beyond an id.

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?

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 declare mutation (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true), so the safety bar is lower. The description nevertheless adds real behavioral context beyond them: the token cost (5 from the compute bucket, scaled and rounded up), refusal on over-cap requests with the estimate returned, and guidance to read agreementBefore/agreementAfter rather than loss. Minor gap: it doesn't say whether the fitted multipliers persist or are reversible.

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 purpose is front-loaded and every sentence carries information, but the prose is dense and jargon-laden, mixing rationale and constraints into long clauses. It is longer than needed for a 3-parameter tool and could be tightened without losing 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?

With no output schema, the description carries the return-value burden and does it ('Read agreementBefore/agreementAfter, not the loss'), plus caps, cost, and refusal semantics. An agent has everything required to build a valid, in-budget request.

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 baseline is 3, but the description adds genuine constraint semantics: at most 16 groups, each non-empty, no transition in two groups, and the work-estimate cap formula (loss evaluations × candidate moves × realizations × horizon). These are usage rules the schema fields do not encode.

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 verb and resource ('Distill exact search into the play scorer: fit rate multipliers for named transition groups') with the goal condition ('so play's rankings agree with exact minimax'). It explicitly names the sibling it is not (sim_calibrate) and the axis that separates them, so an agent can route 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?

Provides explicit when-to-use via the counterpart framing ('This is TACTICAL calibration — the counterpart of sim_calibrate, which learns rates from an event log') and the deliberate division of labor. It even tells the agent how to interpret a null result ('Zero agreement improvement is a finding about the structure, not a failed fit').

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 frames this as a pure read served 'from an index', and its only behavioral caveat is eventual consistency across instances. Annotations instead declare readOnlyHint=false, destructiveHint=true and idempotentHint=false; the non-idempotency is loosely supported by the re-listing sentence, but nothing in the description accounts for a destructive, non-read-only profile. It also adds genuinely useful semantic disclosure (unregistered axis, unwitnessed structural edges), so the conflict, while real, is partial rather than total.

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?

Front-loaded with the core purpose, then layered: indexing/consistency, legacy edges, structural edges, and the isomorphicTo caveat. Dense and long, but nearly every sentence carries decision-relevant information; the isomorphicTo paragraph is the one place that could be trimmed.

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 well by explaining result semantics: the 'unregistered' axis for legacy predicates, 'unwitnessed' edges that prove nothing, and witness ids. Missing pagination/volume behaviour and any mention of ordering, which for an all-relations-of-an-entity query an agent would want.

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?

One required parameter with 100% schema coverage, so the schema already carries the meaning ('entity id to look up'). The description adds the nuance that the id matches against both subject and object positions, but no format or id-scheme guidance beyond that. 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?

Opens with a specific verb+resource+scope: 'List every relation touching an entity, as either subject or object.' That scope statement distinguishes it from directional siblings like sim_neighbors, and the description goes on to define exactly what kinds of edges appear in the result set.

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 activation context ('each call re-lists the store so edges written by other instances are seen') and routes the agent to concrete alternatives for follow-up — GET /api/lineage/{witnessId} and sim_check_witness. It stops short of an explicit when-not-to-use statement, so it is a strong 4 rather than 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?

Annotations already flag this as non-read-only, non-idempotent, and destructive, so the safety profile is covered. The description adds substantive behavioral context beyond the schema: deterministic seeding (seed 11 shared across candidates so differences measure the move, not the dice), the mandatory 'play on SSA' method, and that the response names the engine. 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 purpose is reasonably front-loaded, but the text is a dense single block of em-dashes and stacked parentheticals, and the final sentence about the HTTP endpoint's eliminate/incidence/search methods is lengthy. It is informative but not tightly structured for quick scanning.

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 mentions what the response contains (the engine name), and it covers inputs, prerequisites, method constraints, and the seeding model. For a scoring/simulation tool this is close to complete, with only the return payload's scoring shape left implicit.

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 five parameters are already documented. The description adds conceptual framing for realizations (seeded SSA rollouts) and marking (the position to evaluate from), but does not extend syntax or format beyond 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?

States a specific verb+resource: scoring a player's legal next moves with the PLAY method via seeded SSA rollouts, and indicates which move scores highest. It clearly distinguishes itself from the HTTP evaluate endpoint's eliminate/incidence/search methods, though it does not differentiate from its sim_* 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 states prerequisites (needs the game schema with simulation.objective + simulation.players) and clarifies what the tool does NOT do (the elimination/incidence/search methods belong to the HTTP endpoint), which is useful boundary-setting. However, it gives no guidance on when to pick this over sibling tools like sim_optimize or sim_scenario.

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?

Annotations carry the safety profile, and the description usefully adds the versioning scheme and the three outcome states (ok/refused/uncheckable) plus unit verdicts. However, it never explains the surprising destructiveHint=true / readOnlyHint=false for what it calls a "Fetch" — the one behavioral trait an agent most needs reconciled is left implicit (only "flagged legacy" hints at a side 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?

It is front-loaded with the core verb+resource, which is good, but then condenses versions, verdicts, and three result states into one heavily nested sentence with stacked parentheses. The content is relevant (no output schema), yet the structure is dense enough to slow an agent's parsing.

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 return-value burden and does so thoroughly, enumerating ok/refused/uncheckable and unit verdicts. What remains unexplained is the destructive/read-only status of a tool named "get", leaving one meaningful behavioral gap.

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 sole id parameter is documented as "binding id", so the schema does the heavy lifting. The description restates "by id" without adding format, lookup, or error semantics, matching the baseline 3 for high-coverage schemas.

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 verb and resource ("Fetch a stored Binding by id") and elaborates on the computed check, so the retrieval intent is unambiguous. It distances itself from write tools like sim_bind and sim_run_pipeline, but never explicitly contrasts with the obvious sibling sim_list_bindings, so full sibling differentiation is missing.

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

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

Usage is only implied: an agent can infer you call this to inspect one binding's stored state and current check verdict. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g., use sim_list_bindings to enumerate), so guidance stays at the implied level.

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 explicitly claims 'Linking the same subject/predicate/object again as the same user ... is idempotent: it returns the existing relation's id ... rather than recording a duplicate edge', while the annotations declare idempotentHint=false. The text says the annotation is wrong, which is a direct contradiction an agent could act on. (The otherwise rich detail — auth, attribution, cost, immutability, refusal rules — cannot offset the conflict.)

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?

Purpose is front-loaded in the first sentence and almost every clause carries operational information (refusals, ownership, idempotency, cost). It is, however, a single dense paragraph with long semicolon chains that could be broken into predicate list vs. behavior, making it harder to scan than its content warrants.

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, and the description closes the loop itself by stating what is written ('one Relation, or nothing when it already exists') and the existing:true signal. Combined with the auth requirement, compute-token cost, attribution, immutability, and refusal semantics, an agent has everything needed to invoke and interpret this call.

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 'predicate' parameter has no enum in the schema, so the description carries the load: it enumerates every accepted predicate, gives each one's subject→object type signature, and specifies that 'object' is a /ns/models/v1 type name for @type and a content id otherwise. That is substantive semantics well beyond the 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 opening sentence states a specific verb+resource+scope ('Record a typed edge between two stored entities ... using a registered predicate') and immediately distinguishes this tool from siblings (sim_bind, sim_supersede_model, sim_prove, sim_accept_migration) by naming the predicates each of those owns. An agent can tell exactly what this tool writes and what it does not.

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

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

Usage is exhaustively specified: the valid predicate set is enumerated with subject→object type constraints, predicates refused here are listed together with the tool that records them instead, and 'narrower' is called out as the reversed form of 'broader'. It also states when the call will be refused and why (write rule / ownership).

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?

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?

The annotations declare readOnlyHint=false and destructiveHint=true, but the description asserts 'Nothing moves automatically... this read writes nothing: offers are computed on read and never stored.' That is a direct, serious inconsistency about whether the tool mutates state or destroys anything. Per the rubric this contradiction forces the lowest score despite the otherwise rich behavioral detail (pagination, auth, cost, cycle/hop limits).

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?

It is long and written as a single dense block, but it is front-loaded with the core distinction (offered vs stays) and proceeds in topical order: offered edges, staying edges, systems, error cases, permissions, pagination, auth, cost. Almost every clause carries information; the length is justified by the tool's complexity, though line breaks would improve scanability.

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 unreliable annotations, the description covers what a caller needs: the shape of each row class, per-edge fields (passes/refused/unchecked, youMayAccept, writeRule), pagination, auth scopes, anonymous HTTP access, cost, and the cycle/hop/ownership failure modes. Nothing material about invoking it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns above that by adding real semantics: 'after' is the next token from a previous call (100 edges per page), 'predicate' narrows to one stored predicate and a narrower predicate is refused so you must pass broader, and 'model' must be the superseded model. This genuinely enriches the terse schema descriptions.

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

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

States a specific verb and resource — listing what happens to the edges of a superseded model — and immediately differentiates the two edge classes (taxonomic edges OFFERED vs tool-written/structural/legacy edges STAYING). An agent can tell it apart from siblings like sim_edges, sim_accept_migration, or sim_supersede_model without opening any schema.

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 routes the agent to the right follow-up tools: sim_accept_migration to accept an offer, sim_prove to generate a structural successor edge, sim_system/sim_create_system for naming systems. It also states the preconditions for accepting (you own the superseded model or authored the edge, plus the predicate write rule). It stops short of an explicit 'call this before/never instead of X' framing, so it is slightly more context than explicit when-to-use guidance.

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

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

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?

The description states the operation is a read/traversal ('read through the predicate registry'), while the annotations declare readOnlyHint=false and destructiveHint=true. This is a direct conflict about the tool's safety profile, so no amount of extra detail (inverse/symmetric predicate handling, ordering, no de-duplication) can be credited as consistent transparency.

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

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

The core purpose is front-loaded and almost every clause carries operational information (ordering rules, no de-duplication, supersededBy caveat), so there is little waste. However, the middle sentences are dense run-ons packed with parentheticals, which makes the block harder to scan than it needs to be.

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 return-value burden itself, and it does: ordering by timestamp then relation id, the untimestamped tool-recorded edges, and the 'not de-duplicated' caveat. For a two-parameter traversal tool this is complete enough to call 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 already 100%, but the description adds substantial meaning beyond it: predicate semantics for inverse names (read backwards), symmetric predicates (related, closeMatch, both directions), legacy free-form names answered from stored edges, and the special id+hasMember collection case. This is well above the baseline for a fully documented 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 clause gives a specific verb+resource ('one-hop traversal from an entity, read through the predicate registry') and the description explicitly distinguishes itself from siblings such as sim_edges ('sim_edges lists the edge's witnesses') and implicitly from multi-hop tools. An agent can tell exactly what graph operation this performs.

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 usage conditions: omit predicate for all outgoing relations, pass predicate to restrict, use hasMember with a collection id to list members, and unknown names are refused. It never explicitly names an alternative for multi-hop traversal (e.g. sim_reach), so the sibling routing is only partial.

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 cover the safety profile (destructive, non-idempotent, open-world), and the description adds genuinely non-obvious behavior: token cost per 50 samples, refusal conditions with reason, non-negative rate-range constraint, and that every sample is returned with a Pareto flag. It stops short of explaining what the destructiveHint actually means (whether runs persist artifacts), which is the remaining 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?

Front-loads the core operation, then cost and refusal rules in order of decision relevance. The parenthetical example and cost sentence are dense but each earns its place; slightly crowded overall.

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 6-parameter tool with no output schema, the description supplies what the schema cannot: return content (all samples with Pareto flags), cost model, refusal semantics, and the routing fallback. Nothing essential for a correct call 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%, so the baseline is 3, but the description adds real meaning: the non-negativity rule for rate ranges, the purpose of the horizon and sampling loop, and the interpretation of objectives for the caller. It does not re-specify defaults or bounds already 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?

States a specific verb+resource ('multi-objective optimisation over transition rates for a stored model') and elaborates the mechanism (Monte Carlo sampling, horizon runs on the continuous engine, Pareto flagging). It also names the sibling it is not (sim_compare) for models it refuses.

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 the when (trade-off frontier over rate ranges, with a concrete example: 'which staffing is non-dominated on served vs walked out'), the when-not (models with a schedule or a gate are refused), and the alternative (use sim_compare with explicit scenarios).

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 flag destructiveHint=true and openWorldHint=true, and the description usefully explains the source of that cost: 1 token per 50 grid cells, with a 40x40 grid emptying the bucket. It also discloses the refusal condition for non-continuous models. It does not explain failure behavior beyond that, keeping it short of a 5.

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, front-loaded with purpose, then the constraint, then the cost. Dense but every clause carries information; the quoted example earns its place by anchoring the abstract grid concept.

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?

Covers what the tool does, what it returns, the input constraint, and the cost for an 8-parameter tool with no output schema. The only gap is not explaining what happens on failure or how refused models should be handled, 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 description coverage is 100%, so the schema already documents all 8 parameters including range format and bounds. The description adds conceptual framing (two rates varied together, run to the horizon) but no syntax or format detail beyond the schema, so the 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?

States a specific verb and resource: vary two transition rates over ranges, run each combination to the horizon, return the observable's final value as a grid. The concrete example ('which regime of arrivals × restock keeps the queue empty') makes the operation unambiguous and unlikely to be confused with siblings like sim_optimize or 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?

Gives a clear use case and an explicit exclusion: 'Continuous reading: a model with a schedule or a gate is refused with the reason.' It does not name a sibling alternative to use instead when a model has a schedule or gate, so it stops short of full when/when-not/alternatives guidance.

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

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

The description asserts "Pure read; nothing here is written to any model," while the annotations declare readOnlyHint=false and destructiveHint=true. Even if the destructive hint is meant to capture compute-bucket consumption, the description's flat claim of a pure read directly contradicts the declared annotation profile.

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?

Dense but front-loaded: purpose first, then the reliability caveat, then the apply route, then cost semantics. Every sentence carries information, though the em-dash-heavy style makes it slightly longer 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 no-output-schema, zero-required-parameter tool, the description covers caching behavior, default scan scope, cost per model, grade of the result, and the apply path. The one missing piece is an honest reconciliation of the read-only claim with the annotated destructive/idempotent 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains that limit and realizations are cost controls bounded by the per-model Diagnose charge, and that explicit ids exceeding limit are refused. That is more than restating the schema's ranges.

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 verb and resource (propose candidate @type values for stored models) and names the mechanism (a small Diagnose run per model) plus the intended output shape ("QueueingSystem", "ResourcePool"). An agent can distinguish it from sim_link, which the description explicitly identifies as the apply path.

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

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

Tells the agent how results get used ("apply with sim_link(id, "@type", "<Type>"), there is no separate apply tool") and what happens when ids are omitted (scan the visible catalog, truncated to limit). It stops short of an explicit when-not-to-use or prerequisite condition, so it is clear context rather than full routing guidance.

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

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

Annotations already mark the tool as destructive and non-read-only, but the description adds substantial behavioral context: authentication is required even with record=false, costs are 3 tokens or 2 with record=false and 2 with via, budgets are enumerated, and writes happen only when proved and record=true. It also discloses search-budget outcomes, idempotent-like promotion behavior, and what each result status means.

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, very dense block with long nested clauses and repeated phrasing about predicates, budgets, and witness storage. While the opening sentence is front-loaded, the body is difficult to scan and likely overlong for an agent-facing definition. It sacrifices conciseness and structure for exhaustive detail.

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

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

Given the tool's complexity, the definition is complete: it explains all four predicates, what is compared and not compared, how witnesses and refutations are represented, authentication and cost requirements, search budgets, output statuses, and the via promotion path. No output schema exists, but the description still describes results and witness contents adequately.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful predicate-level semantics beyond the schema, including what each predicate proves and does not prove. It also expands on via's derivation shape and the record=false behavior. The parameter meaning is richer than the structured fields alone.

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: proving a structural relation between two stored models and recording it with a witness. It names the exact predicates it supports (isomorphicTo, subnetOf, preservesInvariant, refines) and distinguishes itself from sibling tools like sim_query and sim_check_witness. An agent can tell this is the search-and-record tool rather than a query or checker.

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

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

It gives explicit when-to-use conditions for each predicate and explains the via alternative that promotes an existing sim_query derivation instead of searching. It also names sim_check_witness for re-checking and states that sim_query never closes over these relations because they are not declared transitive. This is unusually complete routing guidance.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, readOnlyHint=false, and idempotentHint=false, so the agent knows this is a mutating, open-world operation. The description adds valuable operational context: it returns the sheet URL, consumes daily quota, and costs 1 token from the account's compute bucket. It stops short of clarifying overwrite behavior or auth requirements.

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

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

The description is front-loaded with purpose, then states the return value and cost implications in two short follow-up sentences. It is appropriately sized and avoids filler, though the first sentence is dense with artifact 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 destructive, open-world publish tool with no output schema, the description covers the key agent needs: what is published, that a sheet URL is returned, and the quota/token cost. It leaves some gaps around overwrite semantics and idempotency, but annotations already flag the destructive nature.

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 both id and scenario are already documented in the schema, including scenario's defaults. The description does not add syntax, format, or validation detail beyond what the schema provides, matching the baseline for high-coverage schemas.

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: publishing a stored model into the signed-in user's Google Sheets, and lists the concrete artifacts produced (workbook, data tabs, charts). It is clearly distinguishable from generic publish siblings, but does not explicitly distinguish itself from sim_publish_app or sim_publish_compare.

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 use case is implied: publish a stored model to Sheets. However, the description says nothing about when to choose this over sim_publish_app, sim_publish_compare, or sim_my_sheets, nor does it state prerequisites 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?

Annotations already declare destructive, non-idempotent, and open-world behavior. The description adds substantial context beyond that: sandboxed opaque-origin serving, no cookies/session, CSP restrictions, upload checks for empty/oversized/off-origin content, and the allowed root-relative /lib/ imports. It leaves some gaps, such as replay/overwrite behavior for an existing app id and how ownership is verified.

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, but it is long and somewhat repetitive, restating off-origin enforcement in both the upload-check and CSP sentences. The component list and runtime guidance are relevant, yet the overall density is higher than necessary for a two-parameter publish 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?

For a publishing tool with no output schema, the description covers the runtime environment, import rules, and validation checks thoroughly. It does not explain what the tool returns, how ownership is enforced, or what happens when republishing over an existing app id, which are meaningful gaps for a destructive write operation.

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 baseline is 3, but the description adds meaning beyond the schema: it specifies that html must be a complete self-contained document derived from the model's view prompt, that root-relative /lib/ imports are allowed, and that checks reject empty, oversized, or off-origin content. This helps an agent construct the html parameter correctly.

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: 'Publish the generated application for a model you own' and defines the artifact as the single-file HTML produced from the model's view prompt. It does not, however, distinguish this tool from sibling publish tools like sim_publish or sim_publish_compare, so an agent cannot route between them from the description alone.

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?

Clear context is provided: the tool applies to a model you own and to HTML generated from that model's view prompt, with detailed runtime and template guidance. It stops short of explicitly comparing this tool to sibling alternatives such as sim_publish or sim_publish_compare, and it gives no exclusion conditions.

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 past the annotations by disclosing that all scenarios run on one shared server-enforced seed, what gets written (comparison table plus trajectory chart rather than per-scenario data tabs), the return value (sheet URL), a rate constraint (same daily publish quota as sim_publish), and a cost model (1 token per scenario from the compute bucket). Annotations only mark it as a non-idempotent, open-world write; the description supplies the operational details an agent needs.

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 carrying distinct payload: what it produces, how it runs scenarios, and its quota/cost constraints. Front-loaded with the primary action and zero 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 two-parameter publishing tool with no output schema, the description covers output form (sheet URL), side effects (comparison table + chart), quota and token cost, and seed-sharing semantics. Nothing an agent needs 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?

Schema coverage is 100% (baseline 3), and the description adds interpretive meaning the schema does not: that the scenarios array is evaluated against one shared seed so differences reflect scenarios rather than random draws, and that sim_compare defaults backfill anything omitted. That context changes how an agent should construct the scenarios parameter.

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 verb (Publish) and resource (multi-scenario comparison into Google Sheets) and explicitly positions itself relative to two siblings: it is 'sim_compare's export' and 'the counterpart of sim_publish for a single scenario'. An agent can distinguish it from sim_compare and sim_publish without opening either schema.

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 routing context by naming sim_compare (whose output this exports) and sim_publish (single-scenario alternative), which tells the agent when this tool is the right pick. It stops short of an explicit 'do not use this when…' exclusion, so it is strong but not 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?

Annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true, idempotentHint=false) are consistent with a tool that writes Query and Result entities, and the description adds substantial context beyond them: sign-in with read scope, 2 compute-token cost, cache invalidation rules, hard limits, refusal-vs-truncation semantics, and how derived structural facts are never stored. This is far richer behavioral disclosure than the 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 purpose is correctly front-loaded in the first sentence, and most sentences carry load-bearing detail. But it is a single monolithic paragraph with no headings or line breaks, cramming query grammar, semantics, limits, auth, cost, and result fields together, which makes it hard to scan and slows an agent parsing it.

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 and a highly complex tool, the description compensates by explaining result fields (status, partialRows, rows, excluded, superseded, support[].pattern, refusals), the limits that trigger refusal vs truncation, auth/cost, and persistence effects. Nothing essential for correct invocation 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 nominally covers the single query parameter, its description is a bare JSON sketch; the tool description fully specifies the grammar (?variables vs constants, 24-hex ids, model kinds), modes, maxHops ranges, which predicates allow closure, backwards walking via object, and legacy-predicate behavior. It adds meaning far 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?

States a specific verb and resource: 'Answer a question over the edge graph between stored models', immediately qualified by the three query modes (bounded paths, closure, conjunctive patterns). An agent can distinguish this from graph-walking siblings like sim_reach, sim_neighbors, and sim_edges without opening any schema.

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

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

Usage is implied by the mode semantics (edge vs path vs closure, and when closure is permitted) and it cross-references sim_check_witness for re-checking derivations. However, it never explicitly says when to choose this tool over siblings such as sim_neighbors, sim_reach, or sim_edges, nor states exclusions. Adequate but with a real routing gap.

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, implying a write operation, which the description confirms by disclosing storage of every answer and a 2 compute token cost. It also discloses refusal conditions, unknown reasons, budget limits, and caching behavior. The destructiveHint is somewhat surprising for a reachability query, but the description clarifies it is a computation that persists results, adding useful context beyond annotations.

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

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

The description is extremely long, dense, and poorly structured, containing multiple run-on sentences and nested clauses. It front-loads the core purpose but then buries essential details in an overwhelming wall of text that is hard for an agent to parse efficiently.

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

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

Given the complexity of reachability analysis, system translation, and multiple answer states, the description is remarkably complete. It covers input semantics, refusal cases, unknown conditions, storage behavior, and re-check paths, leaving no significant gaps for an agent to invoke 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%, so the schema already documents all three parameters including the sparse override and system key syntax. The description adds operational context like refusal rules for negative/fractional counts and data places, but doesn't introduce new parameter-level semantics beyond what the schema provides. 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?

States a specific verb and resource: returns whether a marking is reachable from another in one stored net, with the three possible outcomes spelled out. It distinguishes itself from sim_compose, sim_bind and sim_create_system by explaining exactly which inputs qualify as one net.

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?

Extensively specifies when this tool applies versus alternatives: a sim_compose result qualifies, a sim_bind binding does not, a collection is not one net, and a system qualifies only under witnessed embedding conditions. It also routes to sim_check_witness for re-checking. The when/when-not guidance is explicit and detailed.

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 non-read-only, destructive, non-idempotent, and open-world. The description adds substantial value beyond that: it explains that the original model remains reachable because ids are content addresses, that the result includes a before/after class diff, that assertedClasses are re-verified and costed rather than trusted blind, and that the call costs 2 compute tokens.

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 return value, then moves to the tag/assertedClasses distinction, the resource hint, and the token cost. Every sentence carries decision-relevant information, and the dense but organized phrasing suits a complex 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?

No output schema exists, but the description explains the return value (new model id and before/after class diff). Together with annotations covering safety and cost disclosure, the description provides enough context for this multi-parameter refinement 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?

Schema coverage is 100%, so the schema already documents each parameter in detail. The description still adds conceptual meaning by distinguishing that tags can only split classes while assertedClasses declares a merge and is re-verified and costed, which helps an agent choose between the two levers.

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: refining a model's parameter classes by editing tags or assertedClasses, then re-deriving. It also names the return value, a new model id plus before/after class diff, making it easy to distinguish from sibling tools like sim_classify or 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 explains the two refinement levers and their different behaviors (tags split, assertedClasses merge and are re-verified), which gives clear context for how to use the tool. However, it does not explicitly name alternative tools or state when not to use this one, so it falls short of full when/when-not/alternatives guidance.

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

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

Despite annotations already flagging a destructive mutation, the description adds substantial behavioral detail the annotations cannot convey: the old id keeps working and its commons dedication stands, only the listing moves; a supersededBy edge is written; re-pointing preserves the earlier edge; edges carry no timestamps so the current successor is the returned `current` record; and taxonomic edges are offered for migration, never moved.

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 purpose is front-loaded in the first sentence and every sentence carries real information. It is dense and the edge-ordering sentence is somewhat convoluted, but there is little outright waste for a tool with this much behavior to disclose.

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 mutation tool with no output schema, the description covers the mutation's effect, ownership requirements, edge side effects, the return value (the `current` supersededBy record), and how related edge migration works. Nothing an agent needs 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?

Schema coverage is 100% and both parameters are documented in the schema, so the baseline is 3. The description adds meaning beyond that by clarifying the ownership constraint ('Both models must be yours') and the semantic role of each id (old keeps working, new is the successor), which the schema alone doesn't state.

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 verb and resource: 'Mark an old version of your model as replaced by a newer one.' It is immediately distinguishable from siblings like sim_delete_model, sim_create_model, and sim_accept_migration because it defines the supersession relationship rather than deletion or creation.

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 preconditions ('Both models must be yours') and routes related operations to siblings: sim_migration_offers and sim_accept_migration for taxonomic edges, sim_edges/sim_neighbors for inspecting the recorded edge. It doesn't explicitly say when to choose this over an alternative, 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 closes with 'Public: no sign-in; costs 1 compute token ... writes nothing', i.e. it presents the tool as a pure read/search with no mutation and zero destructive effect. The annotations declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, which directly contradicts that claim. Per the rubric this is 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?

For a 6-parameter tool this is a massive wall of text with deeply nested parentheticals and version tags (system-view-v2, binds-port-v3, bindable-v3, pipeline-loop-v1). The three forms are listed up front, which helps, but the volume is wildly disproportionate and most sentences are not skimmable.

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 carries the return-shape burden and does so exhaustively: view fields (models, bindings, edges, shape), row contents, and failure statuses (truncated, incomplete, unreadable, notKept, partialRows/partialSystems). Combined with token charges and index bounds, an agent has nearly everything needed despite the absence of an output 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 baseline is 3, and the description adds real meaning the schema lacks: 'among (a collection's model members, at most 256, or a system's models)' with its excluded/closesLoop semantics, and direction 'needed only when the element declares both'. It does not add syntax beyond that, so not a 5.

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 enumerates the three call forms precisely ({id} system view, {model, port, direction?, among?} bindable-port search, {naming} reverse lookup) and repeatedly contrasts itself with siblings like sim_query, sim_reach and sim_bind. That is far more specific than a tautology, but the actual purpose is buried under thousands of words of nested detail, so an agent must excavate it rather than read it.

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 names alternatives explicitly and gives routing conditions: 'For "what contains this pattern?" ask sim_query with closure', the sim_query snippet for refines, and the note that 'This is not refines' and 'sim_reach then answers on that net'. That is genuine when-to-use guidance, though it is scattered rather than front-loaded and there are no clean exclusions up front.

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