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

Despite annotations providing minimal hints, the description thoroughly discloses behavior: append-only (no chainlock_delete), refusal conditions (no-fact, unknown chain, card-cap), the godlock.uk exclusion, the confirm/dry_run gate, and the distinction between consent and tenant auth. This goes far beyond the annotation 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?

The description is long but every sentence earns its place. It front-loads the core action, then exclusions, then behavioral rules, then parameter details and output summary. No filler; the structure guides an agent from decision to invocation.

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

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

For a mutation tool with a runtime gate, aliases, multiple refusal conditions, and a specific output shape, the description covers everything needed: when to call, how to call, what can go wrong, and what is returned. The output schema exists, but the description still explains the return envelope, making it self-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 100%, but the description adds substantial meaning: alias mappings (chain→c, s→subject, f→fact, kind→k), the clipping behavior with empty-after-clip refusal, the precise semantics of confirm as consent (not auth) and dry_run as a preview that still runs safety checks. These details are not fully captured in the schema.

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

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

The description opens with a specific verb+resource: 'Append one fact-bearing stamp to a local ChainLock chain'. It then distinguishes itself from three siblings (chainlock_tip, memory_observe, chainlock_seal) and names the exact conditions for use, making its purpose unmistakable.

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

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

Explicitly states when to use ('when you have a concrete fact to stamp onto a named chain') and when not to ('Do not use it for reading the tip, adaptive memory observation, or sealing LOCKSET'), naming the alternatives. Also covers the session-chain default ('Omit c/chain to stamp the session chain').

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds substantial behavioral detail: depth clipping above 5, default depth of 1, default chain set, refuse=no-stamp when empty, no fact invention, and append-only/no-delete semantics. This goes well beyond the structured annotations 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 dense and front-loaded, with the core purpose and exclusions near the beginning. It is somewhat longer than strictly necessary and repeats a couple of schema defaults (e.g., default chains), but every clause carries operational value and the structure is logical.

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 recall tool with a rich output schema, the description is complete: it defines scope, defaults, edge behavior, alternatives, and return shape. An agent has everything needed to decide when to call it and what to expect.

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

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

Schema coverage is 100%, but the description adds meaning not in the schema: depth values map to behavior ('0 = tip only; 5 = full chain / genesis budget'), out-of-range values are clipped, omitted c/chain scans a specific subset, and q is a case-insensitive substring with empty-q behavior. This significantly enhances the schema's parameter documentation.

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 ('Grounded ChainLock recall at depth 0–5') and specifies output shape ('id+h+fh facts or refuse=no-stamp'). It explicitly contrasts with 'Bayesian rank' and 'tip-only', differentiating it from siblings like memory_recall and chainlock_tip.

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

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

It states exact use conditions ('Use this when you need stamped facts from the local vault') and exclusions ('Do not use it for adaptive memory ranking or reading only the live tip'), naming memory_recall and chainlock_tip as alternatives. It also clarifies defaults for depth and chains, leaving no ambiguity about invocation context.

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

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

The description richly discloses side effects and edge cases: it 'replaces receipts/LOCKSET.json', a later seal overwrites the previous lockset, empty-vault refuses, empty chains are omitted, runtime does not write the public ledger, and dry_run still returns FragGate refuse codes. This goes well beyond the annotations, which only provide broad boolean hints.

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

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

The description is front-loaded with purpose and sibling routing, then systematically covers mutation requirements, edge cases, and return values. It is long but dense; minor redundancy exists because confirm/dry_run/ts semantics are repeated from the input schema descriptions.

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

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

For a mutation tool with no required parameters, the description covers mutation preconditions, refusal paths, overwrite behavior, timestamp limitations, dry-run semantics, and the return value. The output schema supplies the return shape, so nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mostly restates the ts, confirm, and dry_run semantics already present in the input schema, though it adds useful context such as 'Empty {} still attempts the seal' and the relationship between confirm and runtime consent.

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: 'Write a new local LOCKSET over live chain tips' and specifies the exact member fields. It also explicitly distinguishes itself from siblings by naming chainlock_verify, chainlock_append, and runtime_session_close and stating what it is not.

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

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

The tool states exactly when to use it: 'Use this when the operator wants a new local lockset over current tips.' It also gives explicit exclusions and alternatives: 'Do not use it for verify-only, appending one fact, writing godlock.uk, or sealing a raw runtime session; use chainlock_verify, chainlock_append, or runtime_session_close 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 carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds genuine value beyond them: it discloses the empty-chain behavior (returns ok with tip=null and empty=true, not a refuse) and the open-world stance ('Does not invent a missing tip'). This is meaningful behavioral context annotations do not convey.

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

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

The core purpose is front-loaded in the first sentence, and almost every sentence earns its place (usage boundaries, empty-chain semantics, module scoping, default behavior, alias). Slight redundancy: 'This is one card, not depth recall' restates the opening's 'not depth recall', which trims the conciseness score.

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

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

For a low-complexity tool (0 required params, enums for both) with an output schema, annotations, and full schema coverage, the description covers all residual gaps: usage boundaries, default behavior, empty-chain edge case, and return shape. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100% with both parameters fully described including enums, alias relationships, and the omit-to-read-session-chain default, so the schema does the heavy lifting. The description adds only marginal nuance ('not the full vault') beyond what the schema already states; baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource+scope: 'Read only the live tip card of one local ChainLock chain'. It explicitly differentiates from siblings with 'not depth recall and not LOCKSET verify' and later 'This is one card, not depth recall', so an agent can distinguish it from chainlock_recall and chainlock_verify without opening their schemas.

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

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

Explicit when-to-use ('Use this when you need the current tip of a named chain') and when-not-to-use with named alternatives ('Do not use it for depth-0–5 grounded recall, LOCKSET verify, or adaptive memory explain; use chainlock_recall, chainlock_verify, or memory_get instead'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it is fail-closed, does not write the public ledger, does not repair silently, and lists concrete break reasons. It also clarifies that require_seal=true fails closed when no lockset is stored. This is meaningful added context, though it does not detail the exact return shape (output schema exists).

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

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

The description is dense but every sentence earns its place: purpose, usage boundary, side-effect disclosure, fail-closed behavior, break reasons, parameter semantics, and return summary. It is front-loaded with the core purpose and scoping, and the alternative-tool routing appears early. 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 read-only verification tool with an output schema, the description covers the invocation context, the fail-closed contract, the break reasons, the alias behavior, and the require_seal edge case. The output schema handles return-value details, so nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds value by explaining the semantic effect of omitting c/chain ('verify every roster chain plus the stored LOCKSET') and the fail-closed meaning of require_seal=true. It also clarifies that c and chain are aliases. This goes beyond the schema's field-level descriptions.

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

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

The description states a specific verb ('Confirm fail-closed integrity'), a specific resource ('ChainLock chains and LOCKSET'), and explicitly distinguishes itself from appending or sealing. It names the sibling tools it is not (chainlock_append, chainlock_seal), so an agent can select it correctly without opening schemas.

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

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

The description gives explicit when-to-use ('when you must prove local chain integrity before trusting a recall') and when-not-to-use ('Do not use it for appending a stamp or sealing a new lockset'), naming the alternatives. It also explains the omit-c/chain behavior and require_seal=true semantics, leaving no ambiguity about invocation context.

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

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

The description discloses that the tool writes to the ledger ('appends an ask/refuse ledger tip (not idempotent)'), requires confirm=true for mutation, and explains dry_run behavior including returning refusal codes. It also mentions it does not execute domain software and notes the accountable identity. This goes well beyond the sparse annotations (readOnlyHint=false, idempotentHint=false) by providing operational context and side-effect details.

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

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

The description is long but dense with essential information. It front-loads the core action and usage, then covers side effects and parameter nuances. While it could be split into sections, it avoids redundancy with the schema and every clause adds useful detail.

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

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

The description covers the full calling context: purpose, usage, side effects, confirmation requirements, dry_run behavior, identity, and return values (gate view, final_state, ledger_tip, result). It even addresses edge cases like empty {} and optional fields. Given the output schema exists, this is comprehensive for an agent to correctly 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?

Schema coverage is 100% with detailed parameter descriptions. The description adds extra meaning by noting that 'Missing evidence can fail a gate' and 'All proposal fields are optional,' which is not obvious from individual parameter descriptions. It also clarifies the confirm/dry_run semantics in context. This adds value 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 the tool runs the five DecisionGATE gates on a proposal without executing a catalog product. It explicitly differentiates from siblings by saying 'Do not use it for executing a product op or searching the library; use fraggate_call or library_lookup instead.' The verb 'run' plus resource 'DecisionGATE five sequential gates' is specific.

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 explicit when-to-use guidance: 'Use this when you want a gate check without executing a catalog product verb.' It also gives clear exclusions and alternatives, naming fraggate_call and library_lookup. Additionally, it notes the tool runs automatically inside fraggate_call before exec, which helps an agent decide whether to call it directly.

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 only cover the coarse safety profile (not read-only, open-world, non-idempotent, non-destructive); the description adds substantial behavior beyond that: operation-dependent side effects, specific refusal codes (FG-HALLUC-TOOL, FG-STUB, FG-LOCAL-ONLY), that dry_run still runs allowlist/hallucination/stub checks, and that confirm is consent not tenant auth. This is meaningful disclosure the annotations cannot 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?

Purpose and usage are front-loaded, which is good, but the body is heavily bloated with enumerations of all 40 catalog slugs, per-product allowlist op lists, and repetition of confirm/dry_run caveats. Much of this belongs in fraggate_list/fraggate_describe rather than the call tool's own 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?

For a complex 13-parameter mutating tool with a nested claim object and an output schema, the description covers required-vs-alternative params, refusal codes, async behavior, and mutation gating adequately. Return fields are listed but the output schema exists, so that is not a gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: leftover top-level keys become the payload when payload is omitted, shorthand foldlock/fold-preview name/op folding, job_id polling with confirm=true, and background job lifecycle. Its main defect is hedging ('Not the full FragGate door') rather than parameter meaning.

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

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

States a specific verb and resource ('Execute the slug you picked from Softwares through the FragGate single door') and immediately scopes it as the default exec path, explicitly not the catalog and not a raw session. An agent can differentiate it from fraggate_list, fraggate_describe, and runtime_session_exec without opening a schema.

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

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

Gives an explicit when-to-use condition ('when Softwares already returned a slug and a live allowlisted op is known') plus explicit when-not ('Do not use it for picking the catalog slug, searching library papers, or raw session plumbing') with named alternatives (Softwares, library_lookup, runtime_run/runtime_session_exec). This is textbook 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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real behavioral context beyond them: failure mode (missing name and slug, or unknown name, refuses FG-HALLUC-TOOL), stub/live status semantics, and a note that it is 'not execute and not a digest-only proof'. It stops short of describing response shape, but an output schema exists so that is not required.

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 and front-loaded: the purpose and the not-this routing come first, then edge cases, then the return. It is longer than most descriptions and repeats the sibling list, but each clause carries operational information (error codes, live/stub, accepted forms).

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 a low-complexity 2-param read tool with full annotations and an output schema, the description covers purpose, routing, failure modes, and status semantics. What remains (exact card fields) is covered by the output schema, so the definition is complete enough to call correctly.

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

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

Schema description coverage is 100% and the schema already documents that one of name/slug suffices, the combined name/op form, and the FG-HALLUC-TOOL refusal. The description's param remarks largely restate that ('Pass name or slug — one is enough'), so it adds little beyond the structured fields; baseline 3 is appropriate.

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

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

States a specific verb (inspect/describe) and resource (one FragGate registry card) plus the scope ('for the slug you picked'), and explicitly distinguishes itself from fraggate_list, fraggate_verify, runtime_pull, and fraggate_call. An agent can pick this tool over its siblings without opening any schema.

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

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

Gives an explicit when-to-use trigger ('when you already have a name or slug from Softwares, fraggate_list, or GET /v1/software') and an explicit when-not list mapped to named alternatives. Nothing is left to inference.

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, non-destructive, and closed-world. The description adds real value beyond that: it accepts only '{}', it never enables mesh radios, and it never invents tools/ops — a meaningful side-effect guarantee. It also sketches the payload (registry entries, allowlists, digests, MASTER-33 cite), though an output schema already exists.

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

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

The first four sentences are tight and front-loaded, but they are then buried under hundreds of tokens of LIVE_OPS slug dumps presented as 'discovery hints required by product verify scripts'. That bulk does not help an agent decide or invoke anything and repeats data the registry itself returns at call time.

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 essentials are present: no-arg contract, safety profile, routing to the three sibling tools, and an output schema to cover return values. What is missing is any hint about the shape/volume of the registry listing or pagination, and the token dumps add noise without filling a genuine gap.

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

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

Zero parameters, so the baseline is 4. The description correctly reinforces the schema's 'send {}' contract with 'Empty {} only', and does not invent phantom arguments. No additional semantic depth is possible for a no-arg tool.

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

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

States a specific verb+resource ('List hashed FragGate names and digests') and immediately scopes it against the siblings that are NOT it — Softwares, fraggate_describe, fraggate_call. An agent can route correctly without opening any schema.

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

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

Gives an explicit precondition ('when Softwares already returned a slug and you need live, stub, local_only, or digest status') and an explicit exclusion list ('not the first catalog read, inspecting one known card, or executing an op'), each paired with the named alternative tool. This is a textbook when/when-not/alternative routing block.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds rich behavior beyond that: refusal for empty {} and unknown names (FG-HALLUC-TOOL), mismatch returning ok=false with matched=false, and the explicit statement that it does not invent a digest. These are material edge-case disclosures 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?

The description is long but dense with necessary distinctions (registry vs entry, match vs mismatch). It is front-loaded with purpose and scoping, then covers edge cases. No filler sentences, though it could be tightened slightly without losing content. Given the complexity, this is appropriate.

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 three distinct usage modes (digest-only, name/slug, combined) and an output schema; the description covers all combinations, refusal conditions, and the mismatch contract. Nothing an agent needs to call it correctly is missing.

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

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

Schema descriptions cover all three parameters (100%), so the baseline is 3. The description adds cross-parameter semantics: digest-only compares the registry hash, name/slug compares an entry, and combined name+digest must match the card's engine_digest. This relational meaning goes beyond the schema's individual parameter notes.

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 ('Confirm') and resource ('name, slug, or 64-hex engine_digest against the hashed FragGate registry') and explicitly positions it as a proof rather than a listing. It names the sibling tools it is not (fraggate_list, fraggate_describe, fraggate_call), making differentiation unambiguous.

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

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

It provides explicit when-to-use ('when you must prove a listed name or digest exists after fraggate_describe') and when-not-to-use ('Do not use it for listing the registry, describing ops, or executing') with named alternatives. The 'Not an exec path and not a describe card' sentence reinforces exclusions.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavior: unknown ops refuse with FG-UNKNOWN-OP, empty q does not invent a cite, and extra keys are forwarded as corpus payload. It stops short of describing pagination, result limits, or auth requirements, so not a full 5.

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

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

Purpose and routing are front-loaded, which is good, but the description is a dense run-on that repeats the same exclusions twice ('not beliefs and not vault stamps' then 'not a private-file search engine and not AKM/ChainLock') and re-lists the op enum. Several clauses do not 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?

An output schema exists, so return values need not be spelled out, and the description still notes the display-envelope wrapping. Routing, error behavior, and default op are all covered; only minor gaps like limits or auth context remain for this low-complexity, zero-required-param tool.

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

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

Schema coverage is 100% and the schema already documents q, the op enum, the default, and the empty-q behavior, so the description is largely restating structured data. The only marginal addition is clarifying that extra keys ride along as payload — which the schema description already states. Baseline 3 is correct.

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

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

States a specific verb+resource ('Search the Aziel Digital Library for papers and cites') and immediately draws boundaries against siblings by declaring what it is NOT (beliefs, vault stamps, private-file search). An agent can distinguish it from fraggate_call, memory_recall, and chainlock_recall without opening any schema.

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

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

Explicitly names the triggering context ('when you need a library paper, cite, example record, or library skill after Softwares and fraggate_call') and enumerates the negative cases with the exact alternative to use for each ('use fraggate_call for a catalog slug, memory_recall, or chainlock_recall instead'). This is a full when/when-not/alternative routing table.

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?

Discloses that the tool writes a LEARN stamp, is a mutation requiring confirm/dry_run, has no automatic MODEL_UPDATE, and does not authorize actions. It also explains dry_run refusal-code behavior and that confirm is consent, not tenant auth. This goes well beyond the annotations, which are not contradicted.

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

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

The description is front-loaded with purpose and usage, then systematically covers behavior, parameters, and returns. It is dense and somewhat overlong, with minor redundancy around the LEARN stamp and return fields, but it remains structured and each block adds useful context.

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 selection, usage, mutation gates, dry-run behavior, side effects, and key returns. It also clarifies sibling routing and security/permission semantics, so an agent is unlikely to face major gaps when selecting or invoking it.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful cross-parameter guidance: 'subject or memory_id recommended', use_case is a label not a permission, and confirm/dry_run are runtime gates rather than authentication. This extra meaning justifies a 4.

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

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

States a specific operation ('Calibrate one memory') plus the algorithm (AKM-TRIAD-1.0) and explicitly differentiates from 'ranked search' and 'explain view'. It also names sibling alternatives (memory_observe, memory_resolve, memory_get), making selection unambiguous.

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

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

Provides explicit positive and negative conditions: 'Use this when...' and 'Do not use it for...; use memory_observe, memory_resolve, or memory_get instead.' It further clarifies the mutation gate (confirm=true or dry_run=true), so the agent knows when calling is permitted.

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 readOnly/idempotent/non-destructive, and the description adds failure behavior (AKM-NOT-FOUND refusal, no invented nodes), authorization side-effect (authorizes_action stays false), and append-only nature. This is exactly the contextual behavior an agent needs beyond annotations.

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

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

Every sentence carries a distinct fact: purpose, when-to-use, error behavior, alias handling, view semantics. Despite length, it is front-loaded and dense with 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?

With an output schema present, return values need no elaboration; the description covers selection criteria, error/refusal, alias usage, and sibling routing. Nothing needed to invoke correctly is missing.

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

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

Schema coverage is 100%, but description adds alias semantics ('they are aliases, not two different records'), default view behavior ('Omit view for the default node slice'), and a negative lookup constraint ('subject is not a lookup key here'). This exceeds schema detail.

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

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

States a specific verb ('Read'), resource ('one memory's stored explanation'), and explicitly contrasts with 'not a ranked list', distinguishing it from memory_recall. The title 'Explain a memory' aligns and the description names the exact views returned.

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

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

Explicitly says 'Use this when you have a memory_id (or id) and need the stored explanation' and 'Do not use it for ranked adaptive recall or appending an observation; use memory_recall or memory_observe instead.' Also notes there is no memory_delete, preventing misuse.

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

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

Beyond the annotations, the description discloses append-only semantics ('there is no memory_delete'), the mutation gate (confirm=true or dry_run=true), preview behavior, specific error codes (FG-HALLUC-TOOL, FG-STUB, FG-UNKNOWN-OP, FG-LOCAL-ONLY), and that confirm is consent rather than tenant auth and does not upgrade isolation. There is no contradiction with annotations (readOnlyHint=false is consistent with a mutating tool).

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

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

The description is a dense, single paragraph with heavy domain jargon (AKM-TRIAD-1.0, FG-*, ChainLock, hash-only cards, AKM-NO-FACT). Sentences like 'Posterior ≠ truth' and 'Write: additive learn-chain stamp' are cryptic and do not clearly help an agent decide to call the tool. It repeats information already present in the schema (e.g., fact required, confirmation gate) and lacks clear structure or front-loading, making it harder to parse than necessary.

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

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

Given the high complexity of this tool—multiple failure modes, mutation gates, dry-run semantics, and consent caveats—the description is thorough and covers all relevant operational details. It even explains what happens in preview mode, error codes that can be returned, and the limits of confirm as consent. Since an output schema exists, the description does not need to explain return values, and this description is complete enough for an agent to call the tool correctly.

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

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

The schema coverage is 100% and the schema itself already provides rich descriptions for every parameter, including the required fact, the confirm/dry_run behavior, and subject/memory_id/use_case. The description mostly repeats this information ('fact is required (≤160). subject/memory_id/use_case optional') and adds little new semantic meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Append the first memory_observation to the ChainLock learn chain'. It explicitly distinguishes this from sibling operations ('not an outcome resolve and not a grounded ChainLock append') and names the tools to use instead (chainlock_append, memory_resolve, memory_recall). An agent can tell this tool apart from its siblings without inspecting schemas.

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

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

The description gives explicit when-to-use guidance ('Use this when you have a new fact to observe before resolve/calibrate') and when-not-to-use guidance with specific alternatives ('Do not use it for grounded ChainLock append without AKM, resolving an outcome, or ranked recall; use chainlock_append, memory_resolve, or memory_recall instead'). This is the gold standard for usage 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?

Beyond the annotations (readOnlyHint, openWorldHint false, idempotentHint, destructiveHint false), the description surfaces critical behavior: authorizes_action=false, belief_is_not_truth, ChainLock verify failure behavior, refusal modes, ranking caps, and default depth. This is substantial behavioral context that annotations alone do not provide.

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

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

The description is dense and front-loaded with the core purpose. It is longer than average and repeats a couple of points (e.g., 'not raw grounded stamps' and empty-q behavior appear more than once), but nearly every sentence adds a meaningful distinction or safety caveat, so the redundancy is minor.

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

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

Given this tool's complexity, the presence of an output schema, and the rich sibling set, the description is complete: it covers failure modes, default behavior, cap limits, permission semantics, and how it differs from related tools. An agent has enough information to decide when and how to call 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?

Although the input schema already covers all parameters (100% coverage), the description adds important semantics beyond the schema: q is 'lexical rank text, not a SQL filter', empty q still triggers verify-then-rank, depth defaults to 5 unlike chainlock_recall's 1, limit clips the capped list, and use_case is explicitly not a permission.

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: 'Ranked adaptive recall after ChainLock verify'. It explicitly differentiates from siblings by stating it returns a belief list 'not raw grounded stamps, not a public corpus cite, not one-id explain' and names chainlock_recall, library_lookup, and memory_get as the alternatives for those cases.

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

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

It gives explicit when-to-use guidance ('Use this when you want a ranked belief list after verify') and direct when-not-to-use guidance with named alternatives ('Do not use it for grounded ChainLock recall, library search, or explaining one memory_id; use chainlock_recall, library_lookup, or memory_get instead'). It even contrasts the default depth with chainlock_recall, leaving no ambiguity about 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?

Annotations already indicate mutation (readOnlyHint=false), but the description adds substantial behavioral detail: it is 'additive', does not rewrite prior observations, requires a runtime confirm gate, and explains dry_run semantics including which FragGate error codes it returns. It also clarifies that confirm is consent, not tenant auth, and does not upgrade isolation. This is far beyond what annotations convey.

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

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

The description is long but densely packed with necessary information for an 8-parameter mutation tool with multiple failure modes. It is structured with clear sentences covering purpose, usage, constraints, gating, and return value. It is slightly repetitive (e.g., 'confirm is consent' appears once in description but is also in schema), yet every sentence earns its place given the complexity.

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

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

Given the tool's complexity, the description is remarkably complete: it explains the AKM-TRIAD-1.0 standard, the distinction between UNKNOWN and MISS, the additive nature, the refusal codes (AKM-NO-MEMORY, FG-HALLUC-TOOL, etc.), the confirm/dry_run gating, and the return format. The output schema likely covers the stamp structure, but the description tells the agent what to expect functionally. Nothing essential is missing.

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

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

While schema coverage is 100%, the description adds cross-parameter meaning that the schema alone cannot: the conditional requirement 'memory_id or a previously observed subject', the optionality of outcome (omit for UNKNOWN), the mutual exclusivity of confirm and dry_run as the mutation gate, and the distinction of UNKNOWN from MISS. It explains how dry_run affects the call without writing, which is not evident from individual parameter descriptions.

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

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

The description opens with a specific verb+resource: 'Append a memory_resolution outcome on an already-observed memory', and immediately distinguishes it from siblings by saying 'Use this when an observed memory_id or subject now has an outcome' and explicitly excludes memory_observe, memory_calibrate, and memory_get. It also clarifies 'UNKNOWN is distinct from MISS' and 'Does not rewrite history', which fully differentiates it from any other tool.

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

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

Provides explicit when-to-use and when-not-to-use guidance, naming the alternatives (memory_observe, memory_calibrate, memory_get) and the exact condition for this tool ('an observed memory_id or subject now has an outcome'). It also states the precondition 'Requires memory_id or a previously observed subject' and the mutation gate (confirm=true or dry_run=true), leaving no ambiguity.

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 only the safety profile (readOnlyHint false, destructiveHint false, openWorldHint false), and the description goes well beyond them: it discloses refusal codes (MESH-BAD-INPUT, MESH-NO-PUBLISH, MCP-CONFIRM-REQUIRED), the confirm/dry_run mutation gate, the fact that dry_run still runs allowlist/stub/hallucination checks, and that confirm is consent rather than tenant auth. That is rich behavioral context that an agent cannot get from the annotations alone.

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

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

The description is front-loaded and every section carries information, but it is dense and repetitive: 'confirm is consent, not tenant auth, and it does not upgrade shared public-demo isolation' appears in the description and again in both confirm and dry_run schema descriptions. The parenthetical asides ('local sibling, not a loopback fence of the mesh') add cognitive load without adding selection value.

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

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

For a write tool with a rich output schema already present, the description supplies everything an agent needs: scope, exclusions, gate requirements, refusal codes, and a brief return summary. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description nonetheless adds value by explaining the runtime semantics of confirm and dry_run (gate behavior, error codes returned) and by clarifying that title/product are labels rather than file contents. It stops short of 5 because the sha256 format detail (64 hex) merely restates the schema pattern.

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 ('Register the SHA-256 of a local file as a hash receipt') and explicitly distinguishes itself from publish/upload paths and from the mesh_join sibling. The only drag is the misleading tool name 'mesh_broadcast', which implies broadcasting to a mesh; the description must work to counteract that, so the purpose is clear but not effortless to extract.

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

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

It gives an explicit positive condition ('when the operator already holds a local file and wants only its hash recorded') and enumerates the wrong-tool cases (uploading bytes, publishing video, sending mail, joining a mesh node) with named alternatives (local broadcast, AZMail via fraggate_call, mesh_join). This is exactly the when/when-not/alternatives structure that earns a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds specifics: 'No tethers drop. No implicit heal, no account resurrection, no wipe internals. Repeating still refuses.' It also clarifies the AZMail product-local mail ring, adding useful context for agent disambiguation.

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 structured with a clear purpose statement, usage guidance, and behavioral details. Each sentence adds value—no filler. It front-loads the core purpose and then provides necessary distinctions, making it efficient despite its length.

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 output behavior ('Returns MESH-DISABLE-REFUSED with enabled=true and a stay-on note'), usage scenarios, and exclusions. It also addresses idempotency and the separate product ring, ensuring the agent has all needed information without external references.

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

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

The tool has zero parameters, and the schema description already states 'No arguments. Send {}. Public suite disable is refused.' With 100% schema coverage, no additional parameter documentation is needed. The description focuses on behavior and usage, which is appropriate for a parameterless tool.

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

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

The description explicitly states the tool confirms read-only QNM suite-presence stays ON and that it refuses the disable request with MESH-DISABLE-REFUSED. It also distinguishes itself from siblings by directing to mesh_leave or mesh_enable for other 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?

It provides explicit when-to-use: 'Use this when a client still posts the historical disable route and needs the honest refuse.' It also gives clear exclusions: 'Do not use it for dropping one node or declaring an extra bearer; use mesh_leave or mesh_enable 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?

The description goes far beyond the annotations, disclosing that the operation writes/stores the bearer, is rate-limited, refuses empty objects and login/account/gate names, does not arm/wipe/heal/resurrect accounts, requires confirm or dry_run for mutation, and explains dry_run and confirm semantics. 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 long but dense and front-loaded with the core purpose. Some redundancy exists, such as repeating 'confirm is consent, not tenant auth...' and bearer refusal details also present in the schema, but each sentence generally contributes behavioral or routing 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?

Given the tool's complexity and the presence of an output schema, the description is complete: it covers mutation gating, error conditions, dry-run behavior, authentication boundaries, what the tool does not do, and what it returns. An agent has enough context 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?

Although schema coverage is 100%, the description adds substantial meaning: bearer is required with an example, empty {} is refused, mutation requires confirm=true or dry_run=true, dry_run returns specific FragGate codes, and confirm is consent rather than tenant auth. This is meaningful value 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 opens with a specific verb and resource: 'Declare an extra QNM suite bearer (POST /v1/mesh/enable) — additive presence, not a first-time on-switch.' It clearly distinguishes mesh_enable from siblings like mesh_status, mesh_join, and mesh_nodes, and clarifies it is not a login mesh.

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 ('when an operator wants to declare an additional bearer') and when not to use it, naming the alternatives: 'use mesh_status, mesh_join, or mesh_nodes instead.' This gives an agent unambiguous 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 write, non-destructive, non-idempotent, non-open-world behavior. The description adds substantial behavioral context beyond them: refusal codes, the 5-minute worker TTL distinction, confirm/dry_run gating, the fact that confirm is consent rather than tenant auth, stale-row retention, and error conditions like MESH-SESSION-SEAL and MESH-UNKNOWN-NODE.

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

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

The description is a single dense paragraph of semicolon-separated clauses, many of which repeat schema or annotation details. It is front-loaded with purpose, but the volume and lack of structure make it difficult to parse and exceed what an agent needs for tool selection.

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 a complex 7-parameter mutation tool with output schema, annotations, and sibling alternatives, the description is highly complete. It covers prerequisites, side effects, refusal paths, and the confirm/dry_run runtime gate, leaving no critical invocation context missing.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description restates some semantics (node_id required, presence replacement, heartbeat_mode values, 64-hex tip_hash/prev) but adds little beyond the schema, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: 'Beat one registered node (POST /v1/mesh/heartbeat) — restores live from stale; not a first join.' It distinguishes the action from mesh_join and mesh_leave, so an agent can identify it without opening the schema.

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

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

It explicitly says when to use it: 'when you already have a node_id from mesh_join and transmission radios are LIVE.' It also states when not to use it and names alternatives: 'Do not use it for first-time registration or dropping the node; use mesh_join or mesh_leave 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 only declare the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description goes well beyond: durable hash-sealed join session, persistence until explicit leave or 14 days after last beat, beat-interval semantics per mode, '3 missed beats = stale, not deleted', worker 5-minute TTL, and refuse codes (MESH-OFF, MESH-SESSION-SEAL, MESH-BAD-INPUT) with their triggers. It also clarifies confirm is consent not auth. 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?

It is front-loaded (purpose, then routing, then behavior), but grossly oversized: a dense wall of telegraphic fragments mixing parameter restatement, refuse codes, and edge cases. Many clauses duplicate the 100%-covered schema, so the length is not proportionate to what the description needs to add.

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 high-complexity mutation with an output schema present, the description covers the full lifecycle: trigger conditions, heartbeat behavior, staleness, TTL edge cases, refusal codes, and confirm/dry_run semantics. An agent has everything needed to invoke it correctly; return values are covered by the output schema.

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

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

Schema description coverage is 100%, so the schema already documents defaults, formats, enums, and per-param refuse codes; this sets the baseline at 3. The description largely restates that content (product required, node_id format, presence/heartbeat_mode defaults, confirm/dry_run) rather than adding much new per-parameter meaning, so it earns no lift above baseline.

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

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

States a specific verb+resource+scope: 'Register one product node into the QNM rollup (POST /v1/mesh/join) — first presence, not a TTL refresh.' It immediately distinguishes this from the TTL-refresh sibling, so an agent can tell it apart from mesh_heartbeat without opening either schema.

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

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

Explicit when: 'Use this when transmission radios are LIVE and a catalog product should appear in live/locked/isolated counts.' Explicit when-not with named alternatives: 'Do not use it for refreshing an existing node, reading the roster, enabling radios, or opening an account session; use mesh_heartbeat, mesh_nodes, mesh_enable, or runtime_session_open instead.' Both the trigger and the routing are stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description productively extends these: it scopes destruction to 'that node's presence only', states 'No implicit heal', explains that repeating a missing node_id is a 'no-op/refuse, not resurrection', and clarifies that dry_run still returns FragGate refuse codes. This is significant behavioral context 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 and mostly front-loaded: purpose, usage, and exclusions appear early, followed by behavioral and gate details. It is longer than strictly necessary and somewhat repeats the 'confirm is consent, not tenant auth' point that also appears in the schema, but each sentence carries substantive guidance rather than filler.

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

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

Given the tool's complexity, the annotations, and the presence of an output schema, the description is complete: it covers scope, destructive effect, idempotency edge cases, confirmation/dry_run gates, error-refuse behavior, and return receipt. An agent has enough to decide when to call it and what to expect.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: node_id behavior on repetition, dry_run as a preview that skips writes and ledger stamps, and confirm as consent rather than tenant auth. It still relies on the schema for formal types and requiredness, but the added semantics provide real value.

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

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

Description states a specific action and resource: 'Drop one node from the QNM rollup (POST /v1/mesh/leave)' and explicitly distinguishes it from 'suite-wide radio off' and from mesh_nodes/mesh_status. This gives an agent a precise mental model of what the tool does and how it differs from siblings.

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

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

It gives explicit when-to-use guidance ('Use this when a previously joined node should leave the counts') and explicit when-not-to-use guidance with named alternatives ('Do not use it for turning suite-presence off or listing nodes; use mesh_nodes or mesh_status instead'). It also explains the confirm/dry_run gate required for mutation, leaving no ambiguity about invocation preconditions.

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 this a safe, idempotent read (readOnlyHint, idempotentHint, destructiveHint=false), so the safety profile is covered. The description adds genuinely new behavior beyond annotations: durable rows persist while {slug}-worker rows carry a 5-minute TTL. Return format detail is thin, but the output schema covers that.

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

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

The core purpose and routing guidance are front-loaded, which is good. However, the short fragment sentences ('No scores. No leaderboard. Views/MCP/downloads do not enter QNM-S.') read as tangential scope noise that a node-roster tool does not need, diluting an otherwise efficient statement.

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 values need not be re-explained, and annotations carry the safety profile. The description supplies the roster composition, TTL behavior, and sibling routing an agent needs to call this correctly, though the domain-specific 'QNM-S' clauses add confusion rather than completeness.

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

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

There are zero parameters, and the schema states 'No arguments. Send {}.' at 100% coverage, so the baseline is 4. The description correctly adds no parameter guidance because none is needed.

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?

Starts with a specific verb and resource ('List the QNM node roster') and even enumerates the returned columns (node_id + presence_class), so the agent knows what comes back. It also distinguishes itself from suite totals and mutating siblings. The trailing jargon ('Views/MCP/downloads do not enter QNM-S') slightly muddies an otherwise crisp statement.

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

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

Explicitly states when to use it ('when you need the current node list after mesh_status') and when not to ('Do not use it for suite counts without the roster, or mutating presence'). It names the exact alternative siblings (mesh_status, mesh_join, mesh_leave) for the excluded cases, leaving nothing to inference.

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 cover readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds meaningful context beyond those: 'Never enables radios beyond default suite-presence', 'Read-only suite-presence is ON by default', and network-binding caveats. Some of this is cryptically worded, but it does not contradict the annotations.

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

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

The description is very long and packed with unexplained internal jargon. It is not front-loaded for quick scanning, and many clauses (e.g., 'Kernel-direct fabric wrapper — not MASTER-33; not a second Softwares door') do not clearly help an agent decide or invoke the tool.

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

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

For a complex, zero-parameter suite-rollup tool with an output schema, the description provides ample surrounding context about scope, defaults, and exclusions. It redundantly lists return fields that the output schema already covers, but overall it gives enough to call the tool correctly.

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

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

The tool takes zero parameters and schema coverage is 100%, so the baseline is 4. The description adds nothing about parameters because there are none to describe, which is appropriate.

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

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

States a specific verb and resource ('Read QNM suite rollup totals') and explicitly distinguishes itself from the node roster sibling via 'not the node roster' and 'use mesh_nodes instead'. The heavy domain jargon makes it harder to parse than the ideal, but the functional purpose is clear for an agent familiar with the suite.

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?

Contains an explicit 'Use this when...' clause listing the three rollup sub-resources, and a 'Do not use it for...' clause naming the exact alternative tools (mesh_nodes, mesh_enable, fraggate_call) for each excluded case. This is as explicit as usage routing gets.

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 convey readOnly, idempotent, and non-destructive behavior. The description adds useful context that this is 'URL bootstrap only' and returns a compact product list, which clarifies scope beyond the structured data. No contradictions.

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 the main purpose front-loaded, followed by usage boundaries and alternatives. Each sentence earns its place, though it could be slightly more compact without losing value.

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

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

This is a simple zero-parameter tool with an output schema present, so the description does not need to detail return values. It covers scope, exclusions, and recommended alternatives fully. An agent can confidently invoke it correctly.

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

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

With zero parameters and 100% schema description coverage, the schema fully documents the 'Send {}' requirement. The description reinforces this by noting it is a helper bootstrap. Baseline 4 applies since no parameter compensation is needed.

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 ('Read') and resource ('compact bootstrap of every product skill URL and invoke prefix'), and explicitly distinguishes itself from Software-tab cards and the hashed registry. It names sibling tools it is not, making differentiation trivial for an agent.

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

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

Gives explicit when-to-use ('when a client needs skill URLs in one shot') and when-not-to-use guidance with named alternatives (Softwares, fraggate_list, fraggate_call) and a preferred endpoint for hub Software tabs. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, and the description adds useful non-obvious context: it is an advanced/internal path, not the default agent path, and it does not list hub cards or execute. That extra scope clarification goes beyond what annotations alone convey.

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

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

The description is front-loaded with the tool's purpose and stays reasonably compact, but there is some redundancy: 'not the human how-to', 'rather than the human skill', 'default agent how-to', and 'not the default agent path' all express a similar exclusion. Still, each main fact (purpose, alternatives, exclusions, returns) is present.

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

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

Given the empty input schema, the non-destructive annotations, and the presence of an output schema, the description covers everything an agent needs: what the manifest is, which fields to expect, which tools to use instead, and what the tool does not do. Nothing essential is missing.

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

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

The tool has zero parameters and 100% schema description coverage, so the schema fully documents the call signature. The description adds no parameter detail, but none is needed; the baseline of 4 for a no-parameter tool 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 names a specific verb ('Read'), resource ('machine runtime manifest JSON'), and enumerates key fields (version, role, door=fraggate, engine slugs, registry_digest). It also explicitly differentiates this tool from runtime_skill and fraggate_list, so an agent can distinguish it from siblings immediately.

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

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

Provides explicit when-to-use guidance ('when a client needs the machine manifest rather than the human skill') and explicit when-not-to-use guidance ('Do not use it for the default agent how-to or hashed registry discovery'), naming two alternative tools. This leaves no ambiguity about selection.

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