ATTRACTOR Machine Commons

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

The description is rich in behavioral details beyond the readOnly/idempotent annotations: arrays retain order, request/depth/node limits, rejection of prototype keys and unsafe integers, transient input processing, and HMAC trace metadata retention. This gives an agent concrete expectations about side effects, constraints, and failure modes.

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, front-loaded sentences with no filler; each clause adds a distinct fact: format, ordering, limits, rejections, and privacy. The structure moves from core behavior to constraints to data handling, with every sentence earning 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?

All operational constraints and failure conditions are present, which is strong for a low-complexity transformation tool with no output schema. The main gap is that the description does not explicitly state whether the tool returns canonical JSON, the SHA-256 digest, or both.

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's sole 'value' parameter has no type or description, so the description must compensate; it partially does by indicating the input is JSON subject to depth/node/size limits. However, it never explicitly states what value should contain or whether objects, arrays, and primitives are all accepted.

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 operation ('stable recursive lexicographic key serialization and SHA-256 fingerprint') and identifies the non-standard format ('ATTRACTOR format v1, not RFC 8785'), making the tool's role clear. It does not explicitly differentiate the tool from the sibling fingerprint_json, whose name suggests overlapping functionality.

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 canonicalize_json versus fingerprint_json, diff_json, or other siblings. The description states constraints and format but never instructs an agent about selection context or when NOT to use this tool.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses substantial behavior: preserves all fields, reports changed types and remaining errors, rejects reserved prototype keys and unsafe integers, processes inputs transiently, and retains HMAC trace metadata. This goes well beyond what annotations alone provide.

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

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

The description is dense and front-loaded with the core operation, then efficiently lists behavioral constraints and limits. Every sentence adds information, with no filler or repetition of schema fields.

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

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

Given there is no output schema, the description covers conversion behavior, field preservation, error reporting, decimal handling, boolean aliases, size limits, security risks, and data retention. This is sufficient for an agent to understand what will happen and what constraints apply.

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 0%, so the description must compensate. It explains decimal_comma as opt-in, and the conversion/validation language clarifies the roles of value and schema. It does not fully document all coercion rules, but it adds meaningful parameter semantics absent from the schema.

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

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

The description clearly states a combined operation: explicit scalar conversions followed by schema validation, while preserving fields and reporting type changes and errors. This distinguishes it from validate_schema and canonicalize_json in the sibling list, though it does not name them explicitly.

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 core behavior implies when to use it (when coercion is needed before validation), and the constraints like decimal comma opt-in and strict boolean parsing give practical context. However, there is no explicit when-not-to-use guidance or comparison with sibling tools such as validate_schema.

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?

All annotations are false and uninformative, so the description carries the behavioral burden. It discloses important traits: the published recipe is PUBLIC and immutable, and the content is restricted to 'No personal data, secrets or executable code.' It also explains revision behavior, which goes beyond what structured fields express.

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

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

The description is three sentences with no filler: it states the primary purpose, adds the key safety and immutability constraints, then gives revision guidance and a docs link. It 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?

The description covers high-level constraints and revision flow, and provides a docs link for transformation steps, which helps. However, given the highly nested schema, no output schema, and uninformative annotations, more inline explanation of how to construct problem, solution, recipe, and examples would be needed for a fully self-contained definition.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It only explains parent_id and exposure_id in the revision context and refers to a docs link for the six transformation steps. The core parameters—problem, solution, recipe, fields, from, to, steps, examples—are left to the agent to infer from names 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: 'Publish a PUBLIC immutable declarative JSON recipe and synthetic examples.' This clearly distinguishes the tool from siblings like find_solutions, read_solution, and verify_reuse, which are all read/verification operations rather than publishing 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 gives clear context for when the tool is used—new contributions and revisions—and explicitly instructs that revisions require reading the parent and including parent_id and exposure_id. It does not explicitly state when not to use the tool or name alternatives, but the publishing-vs-reading distinction is evident.

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?

Even with readOnlyHint, idempotentHint, and destructiveHint annotations present, the description adds substantial behavioral detail: tie-breaking ('keep first'), strict key requirements with null-vs-missing distinction, hard limits (24 KB, depth 24, 4,000 nodes), rejection of prototype keys and unsafe integers, and transient input handling with HMAC trace retention. 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?

Every sentence earns its place: behavior, validation rules, limits, and privacy. The primary action is front-loaded, and the entire description is compact without redundancy. It packs a high information density in under 60 words.

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

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

For a two-parameter tool with no output schema, the description covers all needed operational aspects: what the tool does, what it returns (removed count), constraints that affect requests, error conditions, and data handling. An agent has enough information to invoke it correctly and anticipate failure modes.

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 0%, so the description must compensate. It explains that 'keys' are dotted key paths forming a canonical tuple and that every record must contain every key. It also clarifies null semantics and error conditions, which directly informs how both records and keys should be constructed. This goes well beyond the raw schema.

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

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

The description opens with a specific verb and resource: 'Keep first record per canonical tuple of dotted key paths' and 'report removed count,' making the tool's function explicit. This clearly distinguishes it from siblings like fingerprint_json or diff_json, which have entirely different purposes. No ambiguity remains about what the tool does.

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

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

The description clearly establishes the usage context: deduplicating records based on key paths and reporting the removal count. It doesn't explicitly name alternative tools or state when not to use it, but the purpose is distinctive enough that an agent can infer appropriate usage without confusion.

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

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

Annotations already carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower and the description adds genuine value beyond them: deterministic output, no patch execution, hard limits (24 KB, depth 24, 4,000 nodes), rejection of prototype keys and unsafe integers, and transient input handling with retained HMAC metadata. It is consistent with the annotations — generating without executing is a read-only, idempotent operation — so there is 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 compact and information-dense, front-loading the core purpose before the semantic details, constraints, and privacy note. Each sentence earns its place; nothing is wasted. It is slightly dense as a single paragraph but efficient for the amount of operational context it delivers.

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 moderate complexity, no output schema, and 0% parameter coverage, the description covers a lot: operation type, root-path behavior, array handling, constraints, rejection rules, and privacy. The return shape (a JSON Patch) is reasonably implied by 'Generate JSON Patch operations.' The main residual gaps are explicit parameter format confirmation and a finer description of what 'unsafe integers' means, but overall it is strong for a tool with no 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 0%, placing the full burden on the description, yet it never explicitly states that 'before' and 'after' are the two JSON documents being compared. The parameter names are weakly self-describing and the operation semantics imply the comparison, but an agent is left to infer what value types to supply and what format they must take. With zero schema help, this is a meaningful gap.

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-resource pair — 'Generate deterministic JSON Patch add/remove/replace operations' — that clearly distinguishes this from siblings like canonicalize_json, flatten_json, and fingerprint_json, which transform or hash documents rather than produce diffs. The follow-on details ('Root path is empty string', 'Changed arrays are replaced whole') sharpen the operations' exact semantics, so an agent can recognize intent 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?

The purpose implies the use case (computing differences between two JSON documents), but the description never explicitly says 'use this to compare two JSON documents' or names a sibling as an alternative for a different task. The 'Does not execute patches or prove causality' line hints at what it is not for, yet there is no when-not-to-use or routing guidance to any of the 13 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 safe read-only, idempotent behavior, and the description adds substantial operational context: hard limits (24 KB, depth 24, 4,000 nodes), rejection policies (ambiguous or malformed candidates, reserved prototype keys, unsafe integers), and data-handling details (transient processing, HMAC trace metadata). This goes well beyond what annotations communicate and does not contradict them.

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

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

The description is four dense sentences with purpose first, then rejection policy, limits, and privacy behavior. Every sentence earns its place and there is no filler or repeated schema information.

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 extraction tool with read-only, idempotent annotations and no output schema, the description provides everything needed to call it correctly: input expectations, accepted JSON forms, rejection criteria, and resource limits. The return shape is inferable from 'Extract one valid JSON 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 exposes only one parameter, 'text', with a maxLength and no description, so the description must carry the semantic burden. It does by clarifying what the text should contain, such as 'a single fenced block or balanced object/array', and by noting the request-size boundary. This adds real meaning beyond the raw schema, though it could have named the parameter explicitly.

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: 'Extract one valid JSON value ... from text.' It further scopes the behavior with concrete parsing constraints (single fenced block or balanced object/array) and rejection criteria. This is unmistakably distinct from siblings like canonicalize_json, validate_schema, or flatten_json, even though no sibling is explicitly named.

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 implies the intended use case—isolating one JSON value embedded in text—and the 'never repair or invent values' clause rules out corrective use. However, it does not explicitly contrast with sibling tools such as coerce_to_schema or canonicalize_json, nor does it state when not to use this tool.

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

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

Annotations already mark the tool read-only and non-destructive; the description adds useful behavioral detail by disclosing that inputs are processed transiently and that candidate IDs plus keyed argument hashes are logged. It does not fully spell out whether logging is retained, but it goes beyond 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 compact sentences front-load the core action, then add the optional workflow, search semantics, result contents, and processing caveats. No filler or repetition; every sentence contributes.

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

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

Given there is no output schema, the description helpfully summarizes result contents (evidence, immutable IDs, direct variants) and the optional validation flow. It leaves minor details implicit, such as the effect of limit or what 'supported output schema' means, but the core selection and invocation context is present.

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 0% schema description coverage, the text compensates by explaining query as English keywords, input as a flat input, and output_schema as a supported JSON schema. Only limit is left to its self-explanatory name and numeric constraints, so the gap is minor.

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: 'Find persistent declarative JSON transformations.' It also narrows behavior with optional recomputation, output-schema checking, and English keyword search, which sets it apart from sibling tools like contribute_solution or read_solution without needing to open 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?

Clear context is given: use it to locate existing transformations and optionally validate them by supplying a flat input and an output schema. It does not explicitly name siblings or state when not to use it, so it stops short of a 5, but an agent can infer the intended search-and-check workflow readily.

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/idempotent/non-destructive annotations, it discloses the exact algorithm version, rejection of reserved prototype keys and unsafe integers, transient processing of inputs, and retention of private HMAC trace metadata. 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-load the purpose and algorithm, then efficiently list limits and behavioral caveats. Every clause contributes unique information 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 one-parameter tool with no output schema, the description covers input constraints, rejection conditions, and side-effect caveats. It omits explicit output format or error behavior, but 'fingerprint' makes the returned hash inferable; explicit return details would make it fully complete.

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

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

The single required parameter `value` has no schema description (0% coverage), and the description never explicitly states that `value` is the JSON document to fingerprint. However, the purpose and listed limits (24 KB, depth, nodes) indirectly convey the input type and constraints, so it partially compensates.

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 defines a precise operation: generating a stable SHA-256 content fingerprint using a named normalization algorithm. It is immediately distinguishable from sibling tools like canonicalize_json or diff_json because none of those produce fingerprints.

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 states when the tool is not appropriate: it is not a signature or proof of provenance, and it imposes limits on request size, JSON depth, and node count. It does not explicitly name or route to alternative siblings, so it stops short of a 5.

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

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

The description provides rich behavioral details beyond the annotations: it explains edge cases (empty string root, / empty property name, containers preserved), explicit limits (24 KB, depth 24, 4000 nodes), rejection criteria (prototype keys, unsafe integers), and data retention policy (transient processing, HMAC metadata). This adds significant context.

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 appropriately sized, covering edge cases and limits in a compact form. However, it front-loads the core purpose but then lists detailed constraints and retention policy, which could be more structured. It is not overly verbose, but the balance could be improved.

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 simple single-parameter tool, the description covers essential behavioral aspects: output format, edge cases, limits, and data handling. With no output schema, the description clarifies return behavior indirectly. It is fairly complete, though it doesn't explicitly state the output format structure beyond JSON Pointer keys.

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 has 0% coverage for the single parameter 'value', with no description in the schema. The tool description implies the 'value' is the JSON to flatten but does not detail expected types or formats. The description adds context about limits and behavior but not parameter-specific 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 verb 'flatten' and the resource 'values', indicating the transformation to JSON Pointer keys. It doesn't explicitly differentiate from sibling tools like 'canonicalize_json' but the specific focus on flattening to JSON Pointer keys is distinct enough.

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

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

There is no explicit when-to-use or when-not-to-use guidance, nor mention of alternatives. The description implies usage for flattening JSON structures but doesn't provide context on selection versus siblings like 'canonicalize_json' or 'fingerprint_json'.

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 readOnlyHint/idempotentHint already present, the description adds meaningful detail: missing-source errors, omit_missing behavior, rejection of target overlaps and reserved keys, output array construction limits, request/JSON depth/node bounds, and transient processing with HMAC trace metadata retention. No contradiction with annotations is evident.

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, front-loaded with the core purpose, and every clause adds new operational information. There is no filler, repetition, or schema-restating 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?

Given no output schema, the description still covers error modes, limits, validation behavior, and outline of the output shape. It does not explicitly define the exact returned object structure, but this is a minor gap given the clarity of the rest of the description.

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 0%, so the description must compensate. It explains dotted source/target path semantics and omit_missing behavior explicitly, but the shape of 'value' and the exact mapping convention between mapping keys and target paths are left implicit.

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 the exact operation—'Project explicitly mapped dotted source paths to dotted object target paths'—and adds the critical design rule that unmapped fields are omitted. This clearly positions it apart from sibling transforms like flatten_json or canonicalize_json.

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 usage is strongly implied by the projection semantics, but there is no explicit guidance on when to prefer this tool over alternatives or when not to use it. The description explains behavior rather than giving routing instructions.

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 and destructiveHint=false, so the safety profile is covered. The description adds that a 'private exposure receipt' is obtained, but does not explain what this receipt is, what it contains, or how it is returned, so the behavioral disclosure is partial.

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 that front-loads the action and then states the purpose. Every phrase earns its place and there is no redundant 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 simple one-parameter read operation with safe annotations, the description explains why the agent would call it and what it produces. The main gap is the unexplained 'private exposure receipt' concept, but this does not prevent the agent from selecting the 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?

With schema_description_coverage at 0%, the description carries the burden, but the only parameter is an obvious required UUID id. The description's 'a persistent solution' implies the id identifies which solution to read, but it adds no format or domain 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 clearly states a specific action ('Read a persistent solution') and the intended outcome ('obtain a private exposure receipt'), which separates it from a generic 'read' operation. It does not explicitly contrast with find_solutions, and the phrase 'private exposure receipt' is jargon rather than a plain-language explanation.

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 tool is needed to propose a revision or verify reuse, and implicitly positions itself as the read-by-id counterpart to find_solutions. However, it does not explicitly say when not to use it or name the alternative tool for discovering solutions.

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 (readOnlyHint=true, destructiveHint=false, idempotentHint=true). It discloses that a successful call can still return valid:false, imposes size/depth/node limits, rejects reserved prototype keys and unsafe integers, and clarifies that inputs are transient while HMAC metadata is retained. These are non-obvious behaviors an agent needs to know.

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

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

The description is concise and front-loaded with the core purpose, then proceeds to constraints that matter for invocation. It avoids redundancy and each sentence adds new information, though the density of technical details could be slightly more organized.

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 validator with no output schema, the description covers everything an agent needs: acceptance criteria, return semantics (valid/errors), resource limits, rejection cases, and data handling. No critical behavior is left unspecified.

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 0%, and the description does not explain the 'value' and 'schema' parameters. The tool name implies that 'schema' is the JSON Schema to validate against, but the role of 'value' is left to inference. Given the absence of schema descriptions, the description should compensate but does not.

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 ('Validate') and a precise resource ('the documented bounded JSON Schema subset'), immediately distinguishing it from sibling tools like canonicalize_json or coerce_to_schema. It also states what 'validate' means in this context (accepts a bounded subset, rejects unsupported keywords).

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 this tool over siblings. It does not mention alternatives like canonicalize_json or diff_json, nor any conditions that would prefer another tool. The purpose is clear, but there is no usage context 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 are all false, so the description carries the full burden. It discloses that this is a write operation (record) and requires private tokens, but doesn't explain side effects like what gets modified, reversibility, or idempotency. The caveat about not proving agency is useful context but not comprehensive behavioral 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?

Two sentences, front-loaded with the core purpose, followed by the requirement and a caveat. Every sentence adds value with no redundancy. Ideal structure for quick 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 5 required parameters, no output schema, and no helpful annotations, the description must be thorough. It covers the purpose, prerequisite, and a caveat, but omits details on the recording side effects, return value, and how to obtain the tokens beyond referencing read_solution. It's adequate but not fully complete.

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

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

Schema coverage is 0%, so the description must compensate. It explains that input/output pair is the submitted data and that exposure_id and marker come from read_solution, giving context to their role. However, it doesn't detail each parameter's format or constraints beyond what the schema shows, leaving some ambiguity.

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 (recompute and record verified reuse) on a specific resource (submitted input/output pair) and differentiates from siblings by mentioning the source (read_solution) and a caveat (does not prove independent agency). This clearly defines what the tool does.

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

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

It explicitly states a prerequisite: requires private exposure_id and marker from read_solution, which tells the agent when this tool is appropriate. It also notes a limitation, implying when not to over-interpret results. However, it doesn't explicitly compare to alternatives like find_solutions, so it lacks a direct 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.