valem

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

Annotations provide only basic hints (not read-only, not idempotent, not destructive). The description adds substantial behavioral context: it returns an id, fails with isError on invalid specs, appends numeric postfix on id collisions, and instructs the agent to always read the returned id. The browser-mode viewDefinition requirement is also a meaningful behavioral disclosure.

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 paragraph that front-loads the core purpose, then delivers critical gotchas (id postfix, isError, viewDefinition requirement) without redundancy. Every sentence adds essential information, and the referral to a guide for the component catalog is a useful pointer rather than 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?

Given the tool's complexity, the description covers return behavior, error semantics, collision handling, and a mode-specific requirement. The rich input schema and output schema handle structural details, and the description properly alerts the agent to behaviors that structured data cannot convey. It is thorough for a create 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 the baseline is 3. The description adds value beyond the schema by summarizing the spec's role ('JSON schema plus derivations, constraints, and optional effects') and highlighting the viewDefinition requirement in browser mode. This helps the agent understand the semantic weight of the spec parameter without reading nested schema 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 'Create a new model from a declarative ModelSpec' with a specific verb and resource, and outlines what the spec contains (schema, derivations, constraints, effects). It doesn't explicitly contrast with sibling tools like patch_model or evolve_spec, but 'new model' and the resource type make the purpose unambiguous.

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

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

The description gives concrete context for when to include a viewDefinition (remote_with_browser mode) and warns against omitting it, but it does not provide explicit when-to-use/when-not-to-use guidance versus alternatives. Usage is implied rather than stated with 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 destructiveHint=true and readOnlyHint=false, so the tool is known to be destructive. The description adds the specific error behavior: it will fail (isError) if the model does not exist. This is valuable behavioral context beyond the annotations, clarifying a failure mode an agent would otherwise not anticipate.

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, compact sentence that front-loads the primary action and immediately states the error condition. There is no redundancy or wasted wording, making it efficient for an agent to parse.

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

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

Given the tool's simplicity (one parameter, confirmed destructive hint, and likely output schema indicating success/failure), the description covers the essential behavior: removal and the failure case. It does not mention potential side effects like cascading deletions or required permissions, but for this simple operation with annotations, the description is 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?

The only parameter, 'id', has a description in the schema ('The model id.') and the schema description coverage is 100%. The tool description adds no additional semantic detail about the parameter, so it relies on the schema, which is adequate. Baseline 3 is appropriate since schema covers it fully.

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

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

The description clearly states the action: 'Remove a model from the registry.' It specifies the resource (model) and the registry, and adds a failure condition (fails if model does not exist). This distinguishes it from sibling tools like create_model, patch_model, and restore, which involve different operations.

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

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

The description implies usage for deletion but does not explicitly contrast with alternatives or provide context such as preconditions, irreversibility, or when to prefer restore over delete. It lacks explicit 'use when' or 'do not use when' guidance, though the purpose is clear enough that an agent could infer the use case.

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

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

Annotations already set readOnlyHint=true, openWorldHint=false, idempotentHint=true, destructiveHint=false. The description adds that the fetch is access-scoped when modelId is provided)Skip-duplicate of annotation. It also warns about result size limitsatch, which is not in annotations. This is valuable behavioral context beyond the structured fields.

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, front-loaded with the core operation and output format, then the parameter nuance and a practical size warning. No filler or repetition.

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

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

The description covers what the tool returns (base64-encoded bytes), when to use each parameter, and the size limitation. With both input and output schemas present, plus clear annotations, nothing essential is missing 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?

While the schema already documents both parameters with descriptions, the description adds meaning by explaining the distinction between direct store fetch and access-scoped fetch (via modelId), and hints at the size constraint. This goes beyond the schema's parameter descriptions, which are brief. Even with full schema coverage, the added context justifies a score above baseline.

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

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

The description states exactly what the tool does ('Fetch a blob's bytes by id'), how it returns data ('base64-encoded in the result'), and clearly distinguishes the two fetch modes ('Pass 'modelId' to fetch a blob referenced by a specific model (access-scoped); omit it for a direct store fetch'). No ambiguity for an agent to select and use 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?

Explicitly explains when to include modelId vs. omit it, tying the parameter to access scoping. The size warning ('Large blobs may exceed the result-size limit — this channel suits small binaries only') gives practical usage constraint. Even though no alternative tool is named for large blobs, the guidance is actionable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating no side effects. The description adds important context that it runs in an isolated environment and returns merged state without registration. It also mentions a throwaway runtime, which is consistent with read-only behavior. The description adds clarity on the isolation guarantee, which is a valuable extension 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 concise and front-loads the core purpose. It uses two effective sentences: the first covers the operation and outcome, the second states the intended use case. It is information-dense with zero filler, and the key differentiator (isolation) is prominent.

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 complex with nested objects and rich schema, but the output schema exists, so return format is handled. The description covers the purpose, isolation, and intended use. It could mention the return value's shape or any error conditions, but given the annotation safety profile, this is sufficient for a correct invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context that mutations are applied within the dry run, reinforcing the isolation. But it does not explain the structure or constraints beyond what the schema already provides, so it meets the baseline without surpassing it.

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

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

The description clearly states the tool compiles a ModelSpec in an isolated runtime, applies optional mutations, and returns merged state without registration. It distinguishes itself from other tools by emphasizing the dry-run nature and preview capability, which is essential for correct selection.

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

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

The description explicitly states 'Use this to preview the full reactive cascade of a draft spec,' which gives clear context for when to use it. It implies not to use it for final registration or when live registry effects are needed, but it does not explicitly name alternatives or exclusion criteria. Given the many siblings, this is adequate 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it returns either the computed value or the exact error, warns that missing library causes undefined function calls, and explains the effect of constants. It does not contradict any annotation, and the added detail goes beyond what annotations 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 description is well-structured and front-loaded with the core purpose, followed by crucial usage guidance. Each sentence serves a purpose: defining output, giving syntax examples, explaining when to use it, and handling library functions. No filler or redundancy, and it remains compact despite covering four 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 is complete for a tool with four parameters. It covers expression syntax and formatting, default behavior for input, library handling and consequences, and constants binding. The output schema handles return value details, so the description does not need to. An agent can confidently invoke the tool correctly based on this description alone.

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 significantly elevates it. It provides a concrete example for expr ('loan.amount * loan.annualRate / 1200'), explains the library syntax with a full example, and clarifies how constants are bound. These practical details add meaning beyond the schema's property descriptions, helping an agent construct correct inputs.

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 evaluates a JSONata expression against a sample document and returns the computed value or the exact compile/eval error. It also ties the behavior to the runtime compiler, making the purpose distinct and specific. The verb 'evaluate' and target resource 'expression' are unambiguous, and it stands apart from sibling tools like test_spec or validate_spec.

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

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

The description explicitly instructs when to use the tool: 'Use this to verify an expression before putting it in a spec' and explains why it is reliable ('uses the same compiler the runtime validates against'). It also gives guidance on when to pass the library parameter. It does not mention when not to use it or name alternatives, but the provided guidance is sufficient for the typical use case.

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

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

The description discloses that the tool modifies the model (destructiveHint true is consistent), preserves live state, returns the new version, and fails on invalid specs, version mismatch, or schema changes that strand existing state. This adds meaningful detail beyond the annotations, such as specific failure scenarios.

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

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

The description is concise, with two well-structured sentences. The core action is front-loaded, followed by failure conditions and usage preference. No unnecessary fluff or repetition.

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

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

Given the complexity of the nested evolution object, the description provides a high-level overview of its structure and tiers, which is essential for correct usage. It also mentions the return value and failure modes. While not every subfield is detailed, the description covers all critical aspects for an agent to use the tool effectively.

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 of the evolution parameter explains the three tiers (schema, view, constants) and the corresponding upsert/remove operations, which is far more informative than the raw schema alone. The id parameter is self-explanatory. This enriches the parameter understanding significantly.

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

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

The description clearly states the verb 'Apply', the resource 'incremental SpecEvolution diff to a model', and the key behavior of preserving live state. It also explicitly mentions the return value and failure conditions, distinguishing it from other modification tools like mutate or patch_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 clear guidance on when to use this tool: for incremental spec evolution, and it advises preferring targeted diffs over wholesale section resets. It does not explicitly name alternatives or state when not to use it, but the provided guidance is sufficient for most decision-making.

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, idempotent, and non-destructive behavior; the description adds non-obvious context: data comes from an in-memory ring buffer (recent/ephemeral), records include inputs/expression/result, and traces can be bulky. This clearly goes beyond what annotations provide, with 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?

Three sentences with no waste: front-loaded purpose and return type, then a special-case path, then a practical advisory about bulk output. Every clause earns its place.

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

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

For a read-only diagnostic tool with readOnly annotations, the description covers purpose, path syntax, constraint paths, data source, and limit handling. Although there is no output schema, the 'inputs, expression, result' hint gives the agent a sufficient model of the returned trace records.

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 meaning beyond the schema: 'path' accepts a synthetic '$constraint:<id>' form, and 'limit' is motivated by trace bulk. It doesn't add to 'id', but the schema already documents that clearly.

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 ('Explain why a field is what it is') and the exact return artifact: recent derivation/constraint trace records for a path. This distinguishes it from siblings such as get_field (current value) or get_history (change history), and the synthetic path special case reinforces its exact scope.

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 usage direction for constraint paths ('$constraint:<id>') and advises passing 'limit' when trace records are bulky. However, it names no alternatives or exclusions, so an agent must infer from sibling names when to prefer explain over get_field, get_history, or get_audit.

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 already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context on top: 'durable, append-only', 'newest-first', 'one record per committed reactive cycle', and the embedded vs remote/paired storage-mode distinction. This goes well beyond what annotations alone communicate.

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 information-dense sentences with the core purpose front-loaded before the filter and mode details. The parenthetical lists (mutations, derivedUpdated, traces, etc.) add jargon but are relevant to understanding the record contents and earn their place, so the description is efficient without being minimal.

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 read-only query tool with no output schema, the description supplies the important contextual pieces: what a record contains, ordering, durability, filters, and storage-mode differences. An agent has enough to call the tool correctly and interpret the returned records.

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 documents all five parameters. The description groups the filters and clarifies that pathPrefix is a 'canonical address', but it does not add substantial parameter-level semantics beyond what the schema already provides; per the calibration baseline, a 3 is appropriate.

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

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

The description opens with a specific verb and resource ('Query a model's durable, append-only audit trail') and states the ordering and record granularity. It explicitly differentiates itself from siblings by calling itself 'the queryable superset of get_history/explain' and explains how it survives the ring-buffer rollover, so an agent can distinguish it without opening schemas.

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

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

The description gives clear context for when this tool is appropriate: it is the durable superset that outlives the in-memory ring buffer. It names the alternatives (get_history/explain) and the distinguishing condition, but it does not explicitly state when to prefer those alternatives instead, stopping short of full when/when-not coverage.

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 read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral guidance by instructing that it must be called before authoring, that its output should be followed, and that the typical topic count is 0-2. It does not contradict the annotations.

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

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

The description is long but deliberately structured: a front-loaded purpose sentence, a bulleted topic list with one-line definitions, and a closing workflow instruction. There is no filler or repetition, and the evaluative information is efficiently packed.

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 output schema and annotations, the description fully explains the tool's purpose, when to use it, how to select inputs, and what to do with the results. Nothing necessary for correct invocation appears to be missing.

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

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

While the schema already describes the topics parameter at 100% coverage, the description enriches every enum value with a plain-language definition and example, turning an opaque list into actionable criteria. This is far more than the schema alone 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 opens with a clear action and resource: 'Get vetted instructions for the hard modelling shapes this domain involves,' followed by a concrete list of modelling topics. This distinguishes it from sibling model-editing tools by positioning it as a pre-authoring guidance lookup.

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

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

It explicitly instructs the agent to read the model description, pick matching topic IDs, and call this tool BEFORE authoring the spec, then follow the returned instructions. There is no named alternative tool, but the workflow context is unambiguous and no other sibling appears to serve this advisory role.

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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context on top: the result is live, reflects reactive pipeline constraints, and the tool is intended for proactive validation. This is exactly the kind of added transparency the annotations alone do not 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 description is two sentences and both earn their place: the first defines what the tool returns, and the second explains when and why an agent should use it. The core definition is front-loaded, and the usage guidance is compactly wrapped around the reactive-pipeline constraint.

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 fully actionable: it explains the purpose, the timing of use, and the practical benefit of avoiding schema-violation errors. The input schema documents the required parameters at 100% coverage, a output schema exists for return values, and annotations already convey read-only safe and idempotent behavior. An agent has enough to call this correctly.

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

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

Schema description coverage is 100%: both id and path are fully described in the input schema. The tool description does not need to repeat parameter semantics. It adds only the general notion of applying the schema 'to a field,' which maps naturally to the path parameter. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: Get the effective JSON Schema for a field. It goes further by defining the key distinction from a plain static schema: the static schema overlaid with LIVE meta-derived constraints. This clearly differentiates the tool's purpose from siblings like get_field or get_spec.

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

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

The description explicitly tells the agent when to call this tool: check this BEFORE writing a value to learn what the reactive pipeline will accept, instead of discovering an invalid mutation by trying it. This is strong context, though it does not name specific alternative tools or exclusions, so it stops just short of perfect 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?

The note 'Evaluates a LAZY derivation on demand' is the standout contribution — it warns the agent that reading the field may trigger extra computation, information not present in the annotations. The annotations already convey the safe idempotent read profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description adds behavioral context on top.

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 efficient sentences with zero waste: the first declares purpose with a concrete example, and the second highlights the key behavioral trait. Every word earns its place.

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

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

For a two-parameter, read-only lookup with no output schema, this is complete. The annotations carry the safety profile, the description covers purpose and the lazy-evaluation nuance, and the schema documents the parameters — nothing an agent needs to call this 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 schema fully documents both required parameters. The description reinforces the path parameter semantics with a concrete example but adds no additional parameter-level details beyond what the schema already 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 (Get), a precise resource (the value of a single field), and the addressing mechanism (JSON Path, e.g. "$.order.total"). The qualifier "single field" plus the JSON Path example clearly differentiates this from sibling tools like get_state, get_spec, and get_view, which have broader scopes.

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 makes the use case clear: you use this when you need one field's value, addressed by a canonical JSON Path. However, it doesn't explicitly name any sibling alternatives or state when not to use it, leaving the routing inference implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds behavior details: it lists timestamps of committed mutations, limited to 100, in ISO-8601 format. This is useful, but it does not clarify ordering (e.g., most recent first) or explicitly state that uncommitted mutations are excluded (though 'committed' implies it).

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 that front-loads the action and delivers the key constraints (ISO-8601 timestamps, limit of 100) efficiently. No extraneous words or redundant information; it is appropriately concise.

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

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

For a read-only list tool with one parameter and no output schema, the description adequately specifies what the tool returns (timestamps) and its limit. The annotations cover side effects, so nothing essential is missing for an agent to decide when to call it.

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

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

The schema description coverage is 100% for the single parameter 'id', described simply as 'The model id.' The description does not add any additional meaning or constraints beyond the schema, so it meets the baseline for high coverage.

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

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

The description clearly states the verb 'List', the resource 'timestamps of committed mutations', and specifies the limit (100) and format (ISO-8601). This distinguishes it from siblings like get_state (current state) or get_audit (audit trail) by focusing specifically on mutation history.

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

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

No guidance is provided on when to use this tool versus alternatives such as get_audit or get_state. There is no mention of exclusions, conditions, or a preference among siblings, leaving the agent to infer usage from context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds valuable behavioral context beyond that: it returns null when no library exists and lists what the library contains (signature, arity, layer). This is useful and not redundant with annotations. It doesn't explain format details beyond that, but the output schema likely covers structure. 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?

Three sentences, all purposeful: first defines what it does, second gives usage guidance, third states a return edge case. Information is front-loaded with the core purpose before context. Nothing is redundant or fluff.

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 this is a single-parameter read-only tool with a rich output schema and annotations covering safety, the description is complete. It explains what is returned, when to call it, and how to handle a null result. It does not need to explain return format because the output schema is present. No gaps remain.

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% (the single 'id' parameter is described as 'The model id.'). The description does not add any additional meaning about the parameter beyond what the schema already provides. Per the rubric, when schema coverage is high, a baseline of 3 is appropriate, and the description adds no parameter-specific insights.

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

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

The description opens with a specific verb and resource: 'List the JSONata functions and values a model's library exports'. It clarifies what the tool returns (signature, arity, originating layer) and explicitly distinguishes it from sibling tools like get_model_info or get_spec by focusing on reusable expression vocabulary. This is unambiguous and separates it from the 25 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 an explicit call-to-action: 'Call it before writing an expression so you reuse the model's existing vocabulary instead of re-deriving it.' This tells the agent when to use it and the benefit. It also covers the edge case of a model with no library (returns null), which guides handling of a common situation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds that the response includes counts, which is useful context but not a significant behavioral disclosure beyond what annotations already 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 description is a single sentence that is front-loaded with the verb and object, then lists exactly what information is returned. It contains no filler and does not repeat schema or annotation 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 low-complexity read-only tool with a rich output schema and full annotation coverage, the description is largely sufficient. It does not clarify how 'summary info' differs from a full spec retrieval, but the output schema and annotations fill most gaps.

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

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

Schema description coverage is 100%, and the single parameter 'id' is documented as 'The model id.' The description's phrase 'for a model' adds no extra semantic detail beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Get summary info for a model', and lists concrete contents (id, version, derivation/meta/constraint/effect counts). It is clear and informative, but it does not explicitly differentiate this tool from siblings like get_spec or get_field, 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?

There is no guidance on when to use this tool versus alternatives such as get_spec or list_models, and no exclusions or prerequisites are mentioned. The only implied context is that it returns summary info, which is not enough for an agent to reliably choose among many get_* siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety profile is covered. The description adds that it returns the full stored JSON, but doesn't specify additional behaviors like whether it includes computed fields or defaults. It doesn't contradict annotations, so a neutral score is appropriate.

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 short sentence that is efficient and to the point. It clearly states the action and resource without redundancy. However, it could include a brief note on when to use it (e.g., 'to retrieve the full spec for inspection or backup') but is still tightly written.

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

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

For a simple getter with one parameter, complete annotations, and an output schema (even though not shown), the description covers the essentials. It doesn't list edge cases or other details, but given the complexity is low and the schema handles parameter info, the coverage is adequate. Additional info on pagination or error handling would be nice but not necessary.

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%: the parameter 'id' is clearly described as 'The model id.' The description does not add extra meaning beyond that, but with complete schema coverage, baseline 3 is correct. No additional context is needed for this simple 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 ('Get') and resource ('full stored ModelSpec JSON'), with a clear subject (a model). It is distinct from siblings like get_model_info and get_spec, though it doesn't explicitly differentiate itself. The description clearly indicates the action and object, making it easy for an agent to understand its purpose.

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

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

Implies it should be used when you need the full spec, but no explicit guidance about when not to use it or what alternatives exist (e.g., get_model_info for metadata). Without stating exclusions or comparisons to siblings, the agent must infer context from the name and description.

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 already declare readOnly, idempotent, and non-destructive behavior, so the description's extra context is valuable rather than redundant. It discloses the potentially large context cost, explains how pruning and depth collapsing behave, and notes that 'at' reads from mutation history — all beyond what annotations 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?

Three sentences, front-loaded with the core purpose, followed by targeted parameter guidance and an optional timestamp explanation. Every sentence earns its place and there is no redundant restating of the schema or annotations.

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 annotations cover safety and idempotence, the schema covers parameter semantics at 100%, and an output schema exists, the description fully covers what an agent needs to invoke the tool correctly. It even includes edge-case behavior such as absent addresses being skipped.

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

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

The input schema already covers all four parameters with clear descriptions, so the baseline is 3. The description adds meaningful behavioral context beyond the schema, particularly the warning that this is the biggest context cost on large models, the pruning/splicing behavior, and the mutation-history interpretation of 'at'. This raises it to 4.

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

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

The description states a specific verb ('Get'), a specific resource ('a model's merged state'), and clarifies it includes base fields plus computed derived fields. This clearly differentiates it from siblings like get_model_info, get_field, or get_view, which target narrower or different aspects.

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 practical guidance on how to invoke the tool for large models: pass 'paths' to project subtrees and/or 'depth' to cap nesting, and pass 'at' for point-in-time reads. It does not explicitly name alternative tools or exclusion criteria, but the usage context is strong enough for an agent to decide when to use it.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context: it evaluates against 'current state' and returns a 'resolved component tree,' which clarifies what the tool actually computes beyond the 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 no filler: the first states the core action and result, and the second gives the only parameter-level decision the caller needs. Information is front-loaded and every sentence earns its place.

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

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

For a two-parameter, read-only, idempotent tool with an output schema, the description is complete enough to support correct invocation. It covers required id, optional viewId, default behavior, and the returned component-tree outcome; annotations cover side-effect safety.

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 fully documents both parameters. The description's note about omitting viewId for the default view adds slight semantic emphasis, but it largely restates the schema and does not meaningfully expand parameter meaning beyond it.

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

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

The description identifies a specific action ('Evaluate') and resource ('a model's embedded view definition'), with a distinctive outcome: 'resolved component tree.' It is clear, but it does not explicitly distinguish itself from sibling get_* tools such as get_spec or get_state, so it misses the full sibling-differentiation bar.

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 conveys when the tool is relevant: when you need a model's view definition evaluated against current state. However, it offers no explicit guidance about alternatives or exclusions among the many sibling tools, so the usage context is implied rather than stated.

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 establish read-only, idempotent, non-destructive behavior. The description adds key behavioral contours: it returns IDs only, in alphabetical order, restricted to currently registered models, and not full model objects or metadata—no surprises.

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

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

A single sentence where each word earns its place: verb, resource, scope, and ordering are all present with no filler or 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-argument read-only list endpoint, the description fully covers what an agent needs to know: what is returned (IDs), the population (all currently registered models), and ordering (alphabetical). Nothing essential is missing, and no output schema or annotations are contradicted.

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

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

There are zero parameters and schema coverage is trivially 100%. With no inputs, the description has nothing else to add beyond what the schema already conveys, meeting the baseline for parameterless tools.

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 ('List'), resource ('Valem models'), scope ('currently registered'), and ordering ('alphabetical'). Clearly differentiates from sibling tools like get_model_info, which targets a single model, and create/delete/patch, which are mutations.

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 makes the call context explicit: it is for enumerating all currently registered model IDs, so an agent needing just IDs will choose this tool. It does not explicitly name alternatives, but for a zero-parameter list tool the context is clear and there are no exclusions.

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

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

The annotations are all negative (readOnly=false, idempotent=false, destructive=false), so they give the agent essentially no safety profile — the description must carry the load. It does: it discloses that mutations are not idempotent (they trigger effects), that a ROLLBACK returns isError with a structured violation list, and how the reactive pipeline cascades. No contradiction with annotations exists.

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

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

The core purpose and scope are front-loaded in the first half-sentence. Every clause earns its place. The only blemish is the convoluted parenthetical at the end ('the same payload explain serves — omit it…'), which is grammatically tangled and slightly undercuts clarity, though the content is still 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?

The tool is conceptually complex (reactive derivations, constraints, effects, rollback behavior) and the description covers those mechanics well. An output schema exists, so return values need no explanation. The main gap is failing to mention when to use dry_run instead for safe pre-validation, which the sibling list suggests exists; otherwise nothing essential 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% (the schema documents id, mutations, and includeTraces), so baseline is 3. The description adds genuine value beyond the schema by defining the mutation key convention ('canonical JSON Path address'), by giving a worked example of the flat map, and by clarifying the meaning of includeTraces (returns the same trace payload used by explain). That lifts it a notch above baseline.

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

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

The description names a specific action ('Apply field mutations to a model') and resource, and pins down the exact behavior: running the reactive pipeline (derivations recompute, constraints enforce, effects dispatch). It clearly distinguishes itself from read-only/lookup siblings and states the mutation key format. Even a cold agent can tell what it does and how it differs from tools like explain or dry_run.

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

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

It gives a concrete routing rule for the explain sibling ('call explain only when you need the full trace / when a value looks wrong'), and explains when to pass includeTraces:true. However, it does not contrast with other plausible alternatives such as dry_run (which presumably validates without applying) or patch_model. This is a clear-usage hint, but not an exhaustive when-not mapping, so a 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?

The description reveals non-obvious behavior beyond the annotations: it mints versus resumes a pairing, waits up to a minute for approval, returns different statuses, and blocks other tools until success. This is rich behavioral context that annotations alone do not 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?

Although the description is long, the pairing flow is genuinely complex and every sentence earns its place: purpose, timeout behavior, return shapes, user-facing instructions, fallback handling, and repeat-call semantics. There is no filler or repetition.

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

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

With no output schema, the description fully documents the possible return shapes and the required follow-up actions. It also covers failure behavior for sibling tools, making it complete for an agent to invoke and interpret this tool correctly.

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

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

The tool has zero parameters and the schema is effectively fully covered, so there is no parameter ambiguity. The description focuses on behavior and return values, which is appropriate given the empty input schema.

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

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

The description states a specific action ('Pair this MCP session with a browser tab'), identifies the target resource ('hosted Valem sandbox'), and explains the purpose ('so both drive the same live model session'). It is clearly distinct from the sibling model-manipulation tools.

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

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

It explicitly establishes this tool as a prerequisite: 'Every other model tool ... fails with a clear error until pairing succeeds.' It also tells the agent exactly what to do after a pending response: call the tool again, and that the second call resumes the same pairing rather than minting a new one.

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

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

The description is rich with behavioral detail: rollback/schema error handling, reactive pipeline, and JSON Pointer semantics. However, the description explicitly includes 'remove' operations in the patch and gives an example of removing an array item, while the annotations declare destructiveHint=false. This is an annotation contradiction, so the score must be 1 per the rubric.

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

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

The description is dense but every sentence contributes: it defines the operation, gives usage contrast, includes a concrete example, and warns about pointer syntax. It is front-loaded and not wordy, although slightly long due to the rich example.

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 output schema exists, returning values needn't be described. The description covers patch operation detail, path format, relationship to mutate, and rollback/schema handling. It is nearly complete, but the destructiveHint contradiction means the overall contract is not fully safe or coherent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantic detail above the schema: the patch parameter is explained with concrete op examples, the path field disambiguation, and the '-' append syntax. The other parameters are adequately described in the schema.

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

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

The description states a specific verb and resource: 'Apply an RFC 6902 JSON Patch document to a model and run the reactive pipeline.' It also directly distinguishes itself from the sibling tool 'mutate', so an agent can tell exactly what patch_model does without opening the 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 explicitly contrasts with 'mutate' (a flat address→value map) and says a patch expresses array insert/remove/move and test/copy ops. It also clarifies the path syntax is RFC 6901 slash-based pointer, NOT the $-rooted form. This gives clear when-to-use and when-not-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 already indicate destructiveHint=true and readOnlyHint=false. The description adds the concrete detail that it 'overwrites the model's current base state', which clarifies the scope of the destruction. It also discloses the same-model constraint. This goes beyond what annotations provide without contradicting them.

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

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

Two succinct sentences with no wasted words. The primary action and the critical constraint (verbatim snapshot) are front-loaded, making it easy to scan and act on.

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

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

For a 2-parameter tool with no output schema and annotations covering safety, the description covers all essential aspects: what it does, the input format, the overwrite effect, and the same-model requirement. Nothing critical 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% for both parameters, but the description adds valuable semantics: it explains the 'snapshot' must be passed back verbatim and that it must be for the same model. These instructions go beyond the schema's simple 'object' type and improve correct usage.

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

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

States a specific verb 'restore' and resource 'model's state', and clearly distinguishes from siblings by referencing 'snapshot' and the overwriting behavior. The constraint 'must be for the same model' adds specificity, making the purpose unmistakable.

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

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

Explicitly ties usage to a prior 'snapshot' call and specifies the input must be passed verbatim. Does not list alternatives or when-not-to-use, but the relationship to snapshot is clear enough to route the agent appropriately.

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 supplied readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context by noting the snapshot is immutable, point-in-time, and covers derived/meta caches, plus how the returned object should be used for rollback.

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

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

Two sentences with no fluff; the core action is front-loaded and the safety workflow is compactly explained. Every sentence adds distinct value.

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

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

For a one-parameter tool with an output schema and fully declared annotations, the description covers what it does, what it includes, when to do it, and what to do with the result. No crucial behavior is left unexplained.

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

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

Schema has 100% description coverage for its single required parameter, correctly describing it as 'The model id', so the baseline of 3 applies. The tool description itself adds no extra detail about the id parameter, but none is strongly needed for this one-parameter API.

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: 'Capture an immutable point-in-time snapshot of a model's state' including the exact contents (base document + derived/meta caches). It is clearly differentiated from the rollback workflow via restore, though it does not explicitly contrast with the sibling get_state 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?

Provides explicit guidance: 'A natural safety step before a risky evolve_spec' and connects the returned snapshot to the restore operation. It lacks a full when-not-to-use list, but the primary use case and recovery workflow are unambiguous.

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, idempotent, and non-destructive behavior. The description adds useful context beyond annotations: tests run in a throwaway runtime through the real reactive pipeline, and the result includes pass/fail plus per-field path/expected/actual failures. 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?

Two sentences, front-loaded with the core behavior and return value, then the usage context. Every clause earns its place with no fluff or schema repetition.

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

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

Given the output schema exists, the annotations fully cover safety semantics, and the input schema documents the parameters, the description provides the missing behavioral framing: throwaway runtime, real pipeline, test certification purpose, and failure reporting shape. Nothing critical is omitted.

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 have descriptions, so the baseline is 3. The description's 'embedded test cases (or ad-hoc given->expect cases)' roughly restates what the schema already documents for spec.tests and the tests parameter, without adding meaningful parameter-level 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?

The description states a specific action — running embedded or ad-hoc test cases through the real reactive pipeline — and clearly identifies the tool as a certification step before create_model/promotion. This distinguishes it from validation and modeling tools, even without naming 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 gives explicit context: use this to certify domain behavior before create_model or promotion. It does not mention when not to use it or name alternative sibling tools, so it stops short of full exclusion 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 mark readOnlyHint false and destructiveHint false, and the description explicitly describes content-addressed storage, reinforcing idempotency (annotated idempotentHint true). It does not detail error conditions, size limits, or the exact persistence semantics, but the given annotations and text give a reasonable picture of 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?

Two sentences cover purpose, storage behavior, and return type. No redundant details or verbose explanations; the description is direct and information-dense without being overloaded.

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 output schema is present (though not shown), the description maps the response to a struct. Since this is a storage operation (not destructive per annotations) and idempotency is highlighted, the context is sufficient for basic usage. It doesn't mention whether blobs can be deleted or any permission requirements, but the provided context (idempotent, non-destructive) partially covers that.

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?

Both parameters are described in the schema: 'data' as base64-encoded blob content and 'mediaType' with an optional note and default. The description reiterates the meaning of 'data' and mentions the return BlobRef with fields. This is sufficient for an agent to know what to provide.

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

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

Description clearly states the verb ('upload'), the resource ('blob store'), the input format (base64 in 'data'), and the purpose (getting a BlobRef to embed in a model's binary field). Even states the content-addressing behavior, making it unambiguous what the operation does.

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

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

Explains when to use (to embed binary content in a model's binary field) and hints at idempotent behavior (identical bytes yield same blobId). However, it does not contrast with the sibling `download_blob` tool or specify any prerequisites or conditions that would make this tool inappropriate, leaving some usage guidance implicit.

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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing the safety profile. The description adds value beyond this by detailing the response structure (errors + warnings with location and message), which accurately sets expectations about multi-finding validation results rather than a simple pass/fail. No contradiction exists between the 'WITHOUT creating' phrasing and the readOnlyHint annotation. Minor deduction because the description doesn't mention scaling, rate-limit, or size constraints on the spec being validated, which could matter for very large drafts.

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 achieve complete clarity with zero wasted words. The first sentence front-loads the core behavior and return type; the second provides the usage loop (validate → fix → re-validate → commit). Every clause in the description contributes distinct information: behavior, return shape, workflow, and the alternative tool. This is an exemplary balance of brevity and informativeness.

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

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

The tool has an output schema, so the description appropriately avoids re-explaining return types, focusing instead on the validation workflow context. Given the annotations cover the safety profile (read-only, idempotent) and the output schema covers the response shape, the description ties everything together with the draft-iteration use case. Small gap: it doesn't hint at performance expectations for large specs or note edge cases like validation timeouts, but these are niche concerns for a validation utility.

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 with a single 'spec' parameter documented as 'The ModelSpec to validate', the schema carries all the weight. The description itself adds no parameter-level guidance about what constitutes a valid ModelSpec or how deeply it validates (e.g., does it validate nested tests/effects/constraints?). Per calibration, when schema coverage is high the baseline is 3, and the description doesn't need to restate parameter structure — though it could have added insight on validation semantics without bloating the 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 opens with a specific verb and resource ('Validate a ModelSpec') and immediately differentiates the tool from its sibling create_model with the emphatic 'WITHOUT creating it'. It then specifies the exact return shape (a 'valid' flag plus structured findings with location and message), leaving zero ambiguity about what the tool does. The contrast with create_model makes the resource scope 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 second sentence explicitly frames the intended workflow: 'Use this to iterate on a draft — fix the reported errors, re-validate — before committing with create_model.' This gives the model a clear when-to-use instruction and names the main alternative tool (create_model). It loses a point because it doesn't discuss related non-mutating siblings like dry_run, test_spec, or evolve_spec where the boundary is less obvious, and there's no explicit 'when not to use' 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?

Beyond the readOnly and idempotent annotations, the description discloses the exact return structure, explains the meaning of a false 'valid', and calls out the embedded-mode special case where no hash chain exists. This is valuable behavioral detail the annotations do not 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 description is brief, front-loaded with the core action, and every sentence earns its place. It provides the essential behavior, the return shape, the interpretation, and an important edge case without wasted words.

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

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

The tool has only one documented parameter, output schema is available, and the description covers both the normal behavior and the embedded-mode special case. An agent has enough context to invoke the tool correctly and to interpret its 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 description coverage is 100% and the single 'id' parameter is already described as 'The model id.' The description reinforces that this id refers to a specific model's audit trail but adds no new semantic detail beyond the schema.

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

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

The description names a specific verb ('Verify'), a specific resource ('tamper-evidence hash chain of a model's durable audit trail'), and explains the result semantics. This clearly distinguishes it from sibling tools like get_audit or get_history, which would retrieve rather than verify.

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

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

The description clearly conveys what the operation checks, and the embedded-mode caveat adds useful context. However, it never explicitly tells an agent when to choose this over get_audit or get_history, so the usage guidance relies on inference rather than direct instruction.

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