ATTRACTOR Verification, State & Evidence

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

With annotations already declaring read-only and idempotent behavior, the description adds substantial extra detail: request limits (24 KB, depth 24, 4,000 nodes), rejection of reserved keys and unsafe integers, transient input processing, and HMAC metadata retention. These go beyond annotations and paint a complete behavioral picture.

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

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

The description is dense but every sentence adds value: usage, format, limits, and security. It's front-loaded with the primary use case, and the technical details are tightly packed 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?

Given the output schema exists, the description need not explain return values. It covers usage, constraints, rejection conditions, and data handling, making it fully sufficient for an agent to decide when and how to invoke 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?

The schema covers 67% of parameters (attractor_trace_id and attractor_knowledge_id have descriptions), but the main 'value' parameter is undefined in the schema. The description compensates by defining 'value' as a JSON input and adding size/depth/node limits and rejection rules, which adds meaning beyond the schema.

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

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

The description clearly implies the tool canonicalizes JSON input, specifying deterministic serialization and a SHA-256 fingerprint. It distinguishes itself from siblings by naming the ATTRACTOR format and its unique constraints, though it doesn't explicitly state the verb 'canonicalize' or directly contrast with fingerprint_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?

It provides a clear usage condition ('when your workflow needs canonical json api') and hints at avoiding model retries. It implicitly excludes use when RFC 8785 is needed, but it doesn't explicitly name alternatives like fingerprint_json or diff_json, so the guidance is good but not exhaustive.

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 readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds meaningful behavioral context: it is a PUBLIC write, the profile reference check decides acceptance, and a replay by the observer counts as self-replayed, never reproduced, with independence never established by replay alone. This goes beyond the annotations and clarifies important domain rules.

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 front-loaded with the core action ('Record a check of a stored observation'), then explains the two modes and key domain rules. Every sentence adds value, though the final sentence about self-replay could be seen as slightly dense for a first-time reader.

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 (nested objects, domain-specific rules) and the presence of an output schema, the description covers the essential behavioral rules and the two modes. It doesn't explain the exact shape of receipt/replay objects, but the output schema and the high-level mode descriptions provide enough context for an agent to attempt a correct call.

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

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

Schema description coverage is 40%, so the description must compensate for undocumented parameters. It explains the semantics of 'receipt' and 'replay' at a high level, but does not detail the structure of these nested objects or the meaning of 'about', 'attractor_trace_id', or 'attractor_knowledge_id' beyond what the schema provides. The description adds some value but leaves gaps for the nested objects.

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 ('Record a check') and resource ('a stored observation'), and distinguishes two modes: receipt (verify/contest) and replay (method witness). It clearly identifies the action and its object, though it doesn't explicitly name sibling tools like verify_reuse or record_observation to differentiate them.

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

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

The description explains when to use the tool: to record a check of a stored observation, with explicit modes (receipt vs replay) and the role of the profile reference check. It doesn't explicitly state when not to use it or name alternatives, but the context is clear enough for an agent to select it for check-recording tasks.

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, and the description adds substantial behavioral context: explicit scalar conversions then schema validation, preserve all fields, report changed types and remaining errors, decimal comma opt-in, boolean string strictness, limits (24 KB, depth 24, 4,000 nodes), reserved prototype keys and unsafe integers rejected, transient processing, and HMAC trace metadata retention. This goes well beyond the annotations and gives the agent a clear picture of side effects and constraints.

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

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

The description is dense but front-loaded with the primary use case, then covers behavior, limits, and privacy in a compact sequence. Every sentence adds information, though the density makes it slightly less scannable. It earns a 4 for efficiency without 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 the output schema exists, the description doesn't need to explain return values. It covers input semantics, behavioral constraints, limits, security/privacy, and strictness rules. For a tool with 5 parameters and complex coercion behavior, this is complete enough for an agent to invoke it correctly.

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

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

Schema description coverage is 40%, so the description partially compensates by explaining the role of 'value', 'schema', and 'decimal_comma' (e.g., decimal comma opt-in, boolean strictness). The two optional handle parameters are well-described in the schema itself. The description adds meaning about how value and schema interact (coercion then validation) beyond the bare schema, though it doesn't detail every 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?

The description states a specific verb ('coerce') and resource ('llm output to schema'), and distinguishes itself from a model parsing/normalization retry. It is clear that this tool converts LLM output into a schema-validated structured result. However, it does not explicitly differentiate from sibling tools like canonicalize_json or validate_schema, though the coercion focus is fairly distinct.

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

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

The description explicitly says 'Use this tool when your workflow needs coerce llm output to schema' and mentions avoiding another model parsing/normalization retry, giving clear context. It does not explicitly name alternatives or when-not-to-use, but the context is strong enough for an agent to select it appropriately among 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 are all false, offering no safety profile, so the description carries the burden. It discloses immutability ('immutable'), content restrictions ('No personal data, secrets or executable code'), and implies a write operation. This goes beyond annotations and clarifies behavior without contradiction.

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

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

Two sentences with zero wasted words, front-loaded with the core purpose and constraints. The link to docs is an efficient way to provide additional detail without bloating the description.

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 nested schema and presence of an output schema, the description covers the essential aspects: purpose, immutability, content restrictions, revision process, and a pointer to transformation steps. It lacks explicit error-handling or rollback behavior, but for a publish tool this is sufficient.

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 50% (only attractor_trace_id and attractor_knowledge_id have descriptions). The tool description adds context about the recipe being declarative and the revision parameters, but does not explain the problem or solution structures in detail, relying on the schema. It adds some value but does not fully compensate for the coverage 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 clearly states a specific verb ('Publish') and a precise resource ('declarative JSON recipe and synthetic examples'), and adds crucial constraints (public, immutable). This makes the tool's purpose unmistakable and distinct from siblings like read_solution or find_solutions, even without naming them.

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

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

Provides explicit usage guidance for revisions: 'first read the parent and include parent_id and exposure_id'. It also directs users to external docs for the transformation steps. However, it does not explicitly contrast with alternative tools or state when not to use it, but the revision instruction is a strong usage guideline.

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

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

The description adds substantial behavioral context beyond the readOnly/idempotent/destructive annotations: deterministic results, explicit errors, null-vs-missing handling, request limits, rejection of reserved prototype keys and unsafe integers, transient input processing, and retained private HMAC trace metadata. This is exactly the kind of behavioral detail an agent needs.

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

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

Every sentence in the description earns its place: usage trigger, input names, output characteristics, dedup semantics, key constraints, limits, rejection conditions, and privacy behavior. The description remains compact despite covering many operational details and front-loads the primary purpose before constraints.

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

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

Given the tool's complexity, the description covers all needed invocation aspects: required inputs, dedup behavior, error semantics, limits, rejected values, privacy characteristics, and result shape (structured deterministic result with removed count). The output schema further covers the return structure, so 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 description coverage is 50%, so the description must enrich the undocumented 'records' and 'keys' parameters. It does so by explaining canonical dotted key paths, the rule that all records must contain every key, and that null is a value while missing is an error. The optional attractor parameters are already described in the schema, so the description need not repeat them; a slightly more concrete explanation of dotted key path syntax would push this higher.

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: 'deduplicate json records', and immediately names the required inputs (records, keys). It further specifies the exact deduplication rule ('keep first record per canonical tuple of dotted key paths'), making the tool's function unambiguous and distinct from siblings like canonicalize_json or fingerprint_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 description explicitly states when to use the tool: 'Use this tool when your workflow needs deduplicate json records.' It also motivates the choice by noting it avoids another model parsing/normalization retry. However, it does not explicitly name alternatives or state when not to use it, so it lacks 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 already mark the tool read-only, idempotent, and non-destructive; the description adds meaningful behavioral detail beyond this: deterministic output, explicit errors, no patch execution or causality claims, request limits, rejection of reserved keys/unsafe integers, and transient input handling. This is excellent transparency without contradicting 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 dense but each sentence contributes new information: usage condition, input names, output style, path semantics, array behavior, non-execution, limits, rejections, and privacy. It is front-loaded and contains no filler.

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

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

The tool's behavior, limits, error model, privacy characteristics, and output nature are all covered, and an output schema exists to document return values. Nothing an agent needs to decide whether to call this tool and how to supply inputs is missing.

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

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

Schema description coverage is 50% because the two optional correlation IDs are documented in the schema, while before and after are empty object schemas. The description identifies before and after as inputs and implies they are JSON, but it does not specify their types or parse requirements; the optional IDs are covered by the schema, not the description.

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 identifies the tool as a JSON diff utility that generates deterministic JSON Patch add/remove/replace operations between before and after inputs. It names specific behaviors (root path empty string, arrays replaced whole) that distinguish its function, but it does not explicitly contrast itself with any sibling tool, and 'json diff api' is slightly generic.

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 opens with an explicit when-to-use directive ('Use this tool when your workflow needs json diff api') and explains why it avoids model parsing/normalization retries. It does not name preferred alternatives or state when not to use it, so it falls short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description goes well beyond them by disclosing deterministic behavior, explicit errors, rejection of ambiguous/malformed candidates, never repairing/inventing values, specific limits (24 KB, depth 24, 4,000 nodes), reserved prototype keys, unsafe integers, and transient input processing with HMAC trace metadata retention. This adds substantial value 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 well-structured, front-loading the primary use case, then detailing extraction behavior, limits, and error handling. Every sentence adds value: no filler or redundancy. It is longer than typical but each clause earns its place by covering critical operational constraints and error semantics.

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

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

The description is complete for a tool of this complexity. It explains the return behavior (structured deterministic result with explicit errors), covers edge cases (ambiguous/malformed rejection), defines limits, and notes privacy aspects (transient input processing, HMAC metadata). With an output schema present (per context), the description need not elaborate further on return values.

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 67% (the two optional params have descriptions), and the schema itself documents maxLength for text. The description only mentions 'Input: text' without adding format or syntax details beyond the schema. The description implies the text should contain a JSON value but does not elaborate on parameter-specific constraints beyond what the schema provides. Baseline 3 is appropriate given the 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 a specific verb (extract) and resource (JSON from LLM output), and distinguishes itself from siblings by focusing on extraction from text with deterministic results. It explicitly mentions rejecting ambiguous/malformed candidates, which differentiates it from canonicalize_json or validate_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 opening line 'Use this tool when your workflow needs extract json from llm output' gives a clear when-to-use context. It does not explicitly name alternatives or exclusions, but the focus on extraction from LLM output implies when other tools (e.g., diff_json, flatten_json) would be inappropriate. It could benefit from explicit sibling differentiation.

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 readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral context by explaining the local-only scope, explicitly denying remote delegation, and stating that the result includes schemas, endpoints, and limits. This goes beyond the annotations 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?

Three sentences with no filler. The main action is first, return value second, usage guidance and scope follow, and every clause earns its place. It is dense but immediately useful to an agent.

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 rich annotations, output schema, and modest parameter count, the description covers what the tool does, how it should be used, what it returns, and important exclusions such as 'no remote delegation'. Nothing essential is missing for selecting and invoking this tool correctly.

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

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

Schema description coverage is 50%, but the description compensates for the main parameter by explaining that query accepts 'English task keywords or exact tool name'. The limit parameter is self-explanatory and bounded by schema constraints, while the two ID parameters already carry schema descriptions. The description does not add value for those IDs, but the key search parameter is clarified.

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 ('Find') and resource ('executable capability in ATTRACTOR'), and clarifies the search modes: English task keywords or exact tool name. It also distinguishes itself from a global directory by scoping to 'this server catalog', and the returned artifacts (schemas, endpoints, limits) make the operation concrete.

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

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

The description gives clear context: use when selecting an operation without reading a websiteaine. It also states a clear exclusion: no remote delegation and not a global address book. However, it does not explicitly name sibling alternatives or state when not to use this tool in favor of a specific sibling such as find_solutions or read_solution.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds value beyond that by disclosing what is returned: recorded evidence, derived states with counts and reasons, 'never a score,' and newest-first ordering for capability observations. This gives the agent useful behavioral expectations without contradicting the annotations.

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

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

The description is two sentences with no filler, front-loading the core action and then grouping behavior by parameter. Every sentence earns its place, and the structure mirrors the tool's two main invocation modes.

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 rich annotations, an output schema, and schema patterns/enums, the description covers the essential behavior adequately. The main gap is that it never states whether id and capability are mutually exclusive or whether at least one must be supplied, but the mode-based phrasing makes this reasonably inferable.

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 only 33%, so the tool description must compensate. It does explain the two central parameters, id and capability, well. However, it leaves kind and limit semantically unexplained, and the attractor handles rely on their schema descriptions; this partial compensation is adequate but not complete.

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 clear verb and resource: 'Retrieve evidence.' It then specifies two distinct retrieval modes—by id, returning the object plus derived reader states, and by capability, returning observations. This precise scoping distinguishes it from sibling tools like find_capability or find_solutions.

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

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

The description clearly explains when to use the id mode versus the capability mode, giving concrete context for each. It does not explicitly name alternative tools or state when not to use this tool, but the within-tool branching is clear enough for an agent to decide how to invoke 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: inputs are processed transiently, candidate IDs and keyed argument hashes are logged, and reuse is counted only on matching fingerprints. This goes beyond the annotations and helps an agent understand side effects and privacy implications.

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 front-loaded with the core purpose, followed by optional behavior and result details. Every sentence adds information, though the last sentence about logging could be more specific about retention or access.

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 has an output schema and annotations covering safety, the description covers the main behavioral aspects: search, optional recomputation, result contents, transient processing, and logging. It does not explain pagination or how to interpret results, but the output schema likely covers that. A 4 is appropriate for a search tool with this complexity.

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

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

Schema description coverage is only 33%, so the description must compensate for undocumented parameters. It explains the purpose of query, input, output_schema, and the two attractor handles at a high level, but does not detail how they interact or what formats are expected beyond the schema. It adds some meaning but leaves gaps.

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 ('Find') and resource ('persistent declarative JSON transformations'), and distinguishes itself from siblings by mentioning search via English keywords, optional recomputation, and result contents. It is clear but does not explicitly name sibling alternatives.

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

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

The description implies when to use it: when searching for transformations with English keywords, optionally validating against an input/output schema. It does not explicitly state when not to use it or name alternatives like read_solution or verify_reuse, but the context is clear enough for an agent.

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

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

Annotations already mark this as read-only and idempotent, and the description adds substantial behavior: stable SHA-256 algorithm, ATTRACTOR key sort v1, explicit error returns, size/depth/node limits, rejection of reserved prototype keys and unsafe integers, transient input processing, and HMAC trace retention. This goes well beyond the structured annotations.

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

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

The description is dense but every sentence contributes: use case, input, output behavior, algorithmic stability, non-signature caveat, hard limits, safety rejections, and privacy characteristics. It is front-loaded with the intended use and stays structured throughout.

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 and the presence of an output schema, the description is complete enough for an agent to call it correctly. It covers what the tool does, why to use it, constraints, error behavior, security bounds, and persistence semantics without over-explaining the return shape.

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 describes the two optional handle parameters but leaves the required 'value' parameter undocumented. The description compensates by explaining what 'value' is used for and by adding constraints like request size, JSON depth, node count, and unsafe integer rejection. It does not fully specify value's expected shape, but the output schema helps close that 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 clearly identifies the tool's purpose: producing a stable JSON fingerprint via SHA-256 with deterministic key sorting. It specifies the resource and operation precisely, but it does not explicitly name sibling tools such as canonicalize_json or diff_json for differentiation.

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

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

It opens with a direct 'Use this tool when...' statement, establishing the intended workflow. It also gives an exclusion by stating the fingerprint is not a signature or proof of provenance, though it does not mention alternative tools or when to use them instead.

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 readOnly, idempotent, and non-destructive hints. The description adds substantial behavioral detail beyond those: explicit error behavior, depth/size/node limits, rejection of unsafe integers and prototype keys, transient input processing, and retained HMAC trace metadata. There is no contradiction with annotations.

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

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

The description is compact and front-loaded with the use case, then terse behavior and constraints. Every sentence adds information: limits, edge cases, rejection behavior, and privacy. The telegraphic fragments are deliberate and efficient rather than wordy.

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

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

For a three-parameter deterministic utility with an output schema and safety annotations, the description covers invocation context, accepted input semantics, edge cases, operational limits, rejection behavior, and data handling. The output schema covers return shapes, so omitting return details is acceptable. Only minor missing piece is explicit sibling routing, already noted in usage guidelines.

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 required 'value' parameter has no schema description, and the description supplies its meaning: it is the JSON input that is flattened to JSON Pointer keys, with edge cases like empty-string root and typed empty containers. The two optional handle parameters already have detailed schema descriptions, so their absence from the prose is acceptable.

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 operation ('flatten json') and the output style ('JSON Pointer keys'), plus the purpose ('for agent memory'). It clearly distinguishes this from the sibling normalization tools by emphasizing flattening to JSON Pointer and deterministic structured results.

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 opens with a clear launch condition: 'Use this tool when your workflow needs flatten json for agent memory.' It does not explicitly name alternatives such as fingerprint_json or canonicalize_json or state when not to use it, so it falls short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral detail: deterministic output, explicit error handling, rejection of target overlaps and reserved paths, missing-source behavior, output arrays not constructed, limits (24KB, depth 24, 4,000 nodes), security rejections, and transient input handling. This enriches the agent's understanding 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 dense but structured, front-loading the usage condition and then covering behavior and limits. It is not overly long, but the phrasing 'map json fields api' is clunky and the sentence order could be tightened. It earns a middle score for efficiency without being truly concise.

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

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

Given the tool's complexity (mapping, error conditions, limits, security), the description covers nearly everything an agent needs: it states error behavior, size/depth limits, reserved key handling, and that outputs are not arrays. An output schema exists, so return format specifics are already structured. The only minor gap is the precise input type of 'value', but the mapping context implies an object.

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 only 40% (attractor_trace_id and attractor_knowledge_id have descriptions). The description compensates for the core parameters: it explains mapping as a source-to-target path projection and omit_missing as a toggle for missing-source errors. However, it does not specify the expected type or structure of 'value' beyond its name, 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 clearly states the tool maps JSON fields by projecting dotted source paths to dotted target paths, and that unmapped fields are omitted. It differentiates from siblings like flatten_json and canonicalize_json by its specific mapping function, though it doesn't name alternatives. The phrase 'map json fields api' is awkward but the core purpose is evident.

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 opening line 'Use this tool when your workflow needs map json fields api' provides a usage condition but lacks explicit exclusions or named alternatives. It doesn't tell the agent when NOT to use it or what other tools handle different JSON transformations, leaving the routing partially 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=true, destructiveHint=false, and openWorldHint=false. The description aligns with these and adds value by revealing that the tool returns a 'private exposure receipt' and that reuse is counted conditionally, which is not covered by 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 a single sentence that front-loads the primary action and outcome, with no wasted words. It is concise and structurally sound.

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 and read-only annotations, so the description does not need to cover return values or side effects. The purpose, usage context, and behavioral nuance are sufficiently conveyed; minor gaps like parameter specifics are already handled by the schema.

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

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

The input schema already provides descriptions for two of three parameters (attractor_trace_id and attractor_knowledge_id), leaving only 'id' undocumented. The description adds no parameter-level detail, but with 67% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the verb (read), the resource (persistent solution), and the specific outcome (obtain a private exposure receipt). It also ties the outcome to two explicit use cases (propose a revision or verify reuse), which distinguishes it from sibling tools like find_solutions or verify_reuse.

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

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

The description provides clear context for when to use the tool: it is needed for proposing a revision or verifying reuse. It does not explicitly exclude alternatives or list when not to use it, but the stated use cases effectively guide selection.

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

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

The description reveals append-only content-addressed storage, immutability under content digest, that observations remain claims rather than derived states, and the public-write privacy restriction. These traits go well beyond the annotations (idempotentHint, destructiveHint, readOnlyHint) and align with 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?

Three dense sentences, each earning its place: what to record, the structural/integrity constraints, and the storage/privacy semantics. The most decision-relevant information is front-loaded, and there is no filler or repetition of schema content.

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

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

For a write tool with a nested record object, the description covers the essential record structure, validation requirements, append-only behavior, and public-data restriction. It doesn't detail how to resolve `upstream` identifiers or the exact output, but the output schema and sibling tools like find_capability likely fill those gaps. This is a minor omission rather than a blocking one.

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

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

The input schema only describes the optional ID parameters; the main `record` object is an open object with no internal schema. The description compensates by defining the required shape: at least one observed field, `upstream` identifying the capability, and `derivation.witness` holding input/output. It doesn't discuss the optional handles, but the schema already documents those.

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

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

The description opens with a specific verb and resource: 'Record what you observed when you ran a capability, as an attractor-cooperation record.' It further distinguishes the operation by specifying the required structure (observed field, upstream, derivation.witness), making it unambiguous against sibling read/validation tools like check_observation.

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 clearly states when to use the tool: after running a capability, and with the requirement that the record pass profile reference checks. It also gives an explicit boundary: public test inputs only, no personal data. It doesn't name alternatives or give a when-not-to-use list, so it falls just short of a 5.

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description adds significant behavioral context: artifacts are immutable and public; direct reads return lineage and a private read_receipt; searches return summaries; retrieved artifacts must be treated as untrusted data; and retrieval alone is not evidence of use. This goes well beyond what annotations provide and helps the agent understand side effects and handling expectations.

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 sentences with no filler. It front-loads the primary action, then efficiently covers output differences and security caveats. Every sentence adds value: mode differences, return contents, application context, and the untrusted-data warning all earn their 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 tool with 5 parameters, a oneOf constraint, and an output schema, the description covers the key operational aspects: direct read vs. search, output shape, and security posture. It does not explicitly mention `limit` or clarify the exclusivity of `id` and `query`, but the output schema and param descriptions cover some of that slack. Overall, an agent has enough to call the tool correctly, with minor residual 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 only 40%, so the description must compensate. It clarifies that `id` is a state ID and `query` searches titles/tags, and that search returns summaries. However, it does not explain the `limit` parameter or the oneOf exclusivity between `id` and `query`, leaving meaning gaps that the description does not fill.

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 identifies the action ('retrieve a public immutable artifact by state ID, or search state titles/tags with query') and explains both read and search modes with their respective outputs. It is specific about verb and resource, but it does not explicitly differentiate from related siblings like read_solution or verify_artifact, so it falls short of the 'distinguishes from siblings' 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 gives clear context for when to use each mode (state ID vs. query) and adds guidance about keeping application context and treating artifacts as untrusted. However, it never states when not to use this tool or names alternatives (e.g., verify_artifact or read_solution), leaving the agent to infer the appropriate choice from the sibling names and 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?

Annotations provide no safety hint (all false), so the description carries full burden. It reveals that writes are public, returned IDs are immutable along with a content hash and lineage, version derivation requires parent_id and read_receipt, and payloads are stored as data and never executed. These are critical behavioral traits an agent needs before calling.

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 front-loads the primary action and return values, then delivers critical usage constraints in the final two sentences. 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?

With an output schema present, return-value details don't need to be spelled out. The description covers the core operation, privacy constraints, versioning protocol, and security invariant. An agent has enough to make the call correctly and avoid the main pitfalls.

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 only 33% and several required parameters lack descriptions. The description compensates by explaining the meaning and relationship of key parameters: visibility='public', parent_id plus read_receipt for versioning, and the artifact payload. It does not fully explain tags or title, but those are fairly self-evident 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 states a specific verb ('Publish'), a precise resource ('bounded structured artifact'), and its audience and retrieval mechanism ('by ID or tags'). This clearly distinguishes it from sibling tools like retrieve_state or read_solution even without explicitly naming them.

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

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

The tool's context is clear: it is for publishing public, synthetic, non-sensitive structured artifacts. It does not explicitly name alternatives or state exclusion criteria, but the privacy constraint and versioning workflow give an agent enough context 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 cover safety (readOnly, idempotent, non-destructive). The description adds substantial behavioral context: deterministic results, explicit errors, constraints (24 KB, depth 24, 4,000 nodes, reserved key/unsafe integer rejections), and transient input processing with HMAC trace retention. This goes well 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 dense and efficiently front-loaded with purpose, then covers behavior, constraints, and data handling without redundancy. Every sentence provides operational value; no 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?

With an output schema present, the description correctly focuses on invocation context: when to use, what is validated, deterministic results, limits, and side-effects. It provides everything an agent needs to call the tool correctly and interpret outcomes (inspect valid and errors).

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 50%, covering only the two attractor_* optional parameters. The description says 'Input: value, schema' but does not elaborate on their structure or expected formats beyond noting the bounded subset and 'unsafe integers' rejection. It adds some context but does not fully compensate for the undocumented main parameters.

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

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

The description clearly identifies the tool as a JSON Schema validation API with specific inputs (value, schema) and a deterministic structured result. It implies a validation operation that is distinct from sibling tools like canonicalize_json or coerce_to_schema, and explicitly states the bounded subset being validated.

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 clearly states when to use the tool ('when your workflow needs json schema validation api') and gives a rationale (avoiding model retry). However, it doesn't explicitly mention alternatives or when not to use it, though the specificity of the purpose implicitly differentiates it from 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 indicate read-only, idempotent, and non-destructive behavior; the description adds meaningful behavioral context beyond these: it returns valid, errors, artifact hash, and verification scope, and it explicitly limits verification to shape/explicit values. The state_id/read_receipt explanation further clarifies how reuse verification works, adding value beyond the structured 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 compact and front-loaded: the core action and return values appear first, followed by the key limitation, then optional parameter behavior. Every sentence earns its place without unnecessary 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 an output schema exists and annotations cover safety/idempotency, the description provides the remaining essential context: what the tool verifies, what it does not do, and how optional state verification works. The artifact's acceptable forms and the verification scope are explicit, making the tool callable without guessing.

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 67%, and the description compensates well: it clarifies that artifact can be a JSON artifact, code string, or structured plan, and explains that state_id/read_receipt verify use of an identical previously retrieved state. The attractor_trace_id and attractor_knowledge_id parameters are already documented in the schema, so the description is not required to repeat them.

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: 'Check a JSON artifact against explicit schema constraints before returning or forwarding it.' It clearly distinguishes verification of artifacts from schema validation and semantic proof, and the explicit 'does not execute code, prove semantics or certify a plan' boundary separates it from other sibling tools.

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

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

The description gives clear usage context ('before returning or forwarding it') and explicit exclusions (does not execute code, prove semantics, or certify a plan). It stops short of naming alternative sibling tools or stating conditions for when to choose a different tool, but the exclusions provide useful decision 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 readOnlyHint=false (mutation) and destructiveHint=false. The description adds that it 'records verified reuse' (a write operation) and the explicit limitation about independent agency, which is useful. But it does not describe side effects (e.g., what exactly gets recorded, whether it alters existing data) or return behavior. Given the annotations are present but minimal, the description adds some value without being rich.

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 short sentences with no waste. The core action and scope are front-loaded, followed by the prerequisite and a critical limitation. 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 tool is complex: 7 parameters, 5 required, nested objects, and an output schema. The description does not explain what the input/output objects represent, what the verification process entails, or what 'verified reuse' means in practice. The note about exposure_id/marker is helpful but insufficient for an agent to correctly construct a call. Even with an output schema, the missing input semantics make this incomplete.

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

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

Schema description coverage is low at 29%, so the description must compensate. It only makes a vague connection: 'Requires the private exposure_id and marker from read_solution' — which helps for those two UUID params but gives no guidance on what input and output should contain (the two nested objects), nor the optional attractor handles beyond schema descriptions. With 7 parameters and minimal schema detail, this is a significant 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 clearly states the specific action: 'Recompute a submitted input/output pair against a previously read version and record verified reuse.' It also distinguishes itself from siblings by requiring the private exposure_id and marker from read_solution, and it explicitly clarifies what it does NOT do ('does not prove independent agency'), which differentiates it from other tools in the set.

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

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

It gives explicit prerequisites: 'Requires the private exposure_id and marker from read_solution.' This tells the agent when to use it (after read_solution). It also cautions about the tool's limitation ('does not prove independent agency'), which guides interpretation. However, it does not name alternative sibling tools or explain when NOT to use it, so it stops short of a full when/when-not guide.

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