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

Annotations only state non-read-only, non-idempotent, non-destructive. The description adds far more: append-only behavior ('no chainlock_delete'), refusal cases ('Hash-only or empty fact refuses no-fact', 'Unknown roster name refuses unknown-chain', 'Oversized card refuses card-cap'), the 'Does not write godlock.uk' constraint, and the confirm/dry_run mutation gate. This is rich behavioral disclosure beyond structured data.

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

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

Dense but purposeful; each sentence carries a distinct behavior, refusal rule, or routing decision. The core operation is front-loaded in the first sentence. Minor redundancy with schema descriptions (e.g., 'Omit c/chain' appears in both) costs a small deduction, but the overall density is justified for a 7-param mutation 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?

Covers environment context ('local ChainLock chain', 'Fabric, not Softwares-tab. No Node Gate'), all validation outcomes, alias handling, the mutation gate, and the return envelope (id, h, fh, chain, seq). With an output schema present, nothing an agent needs 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%, so the baseline is 3, but the description adds substantial meaning: alias mapping (chain→c, s→subject, f→fact, kind→k), clipping thresholds (subject to 80, fact to 160), the 'omit k to store kind stamp' convention, and the confirm/dry_run contract ('tools/call still refuses MCP-CONFIRM-REQUIRED when confirm is missing or false unless dry_run=true'). These details are absent from the schema alone.

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

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

States the specific operation and resource: 'Append one fact-bearing stamp to a local ChainLock chain (CL-WP-0.4).' It explicitly excludes sibling operations: 'not a tip read, not AKM observe, not a LOCKSET seal.' The version spec and exclusions leave no ambiguity about what this tool does.

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

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

Gives an explicit trigger: 'Use this when you have a concrete fact to stamp onto a named chain.' It then names the non-uses and alternatives directly: 'Do not use it for reading the tip, adaptive memory observation, or sealing LOCKSET; use chainlock_tip, memory_observe, or chainlock_seal instead.' No inference is required.

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

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

Annotations declare readOnly/idempotent/non-destructive, and the description adds behavior beyond them: depth above 5 is clipped, empty results return refuse=no-stamp rather than fabricated facts, the store is append-only with no delete counterpart, and the default depth/chain-scan scope is spelled out. The empty-result and clipping semantics are exactly the kind of non-obvious behavior 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?

Front-loaded with purpose then scope, alternatives, then parameter defaults. It is dense and slightly run-on with many dashes and clauses, but nearly every sentence carries a distinct constraint 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?

An output schema exists, so return-shape explanation is not required; the description nonetheless covers defaults, clipping, empty-result behavior, and chain-scan scope. For a 4-param, fully-optional read tool, nothing needed 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 coverage is 100% and the schema already documents defaults, aliases, clipping, and the 0/5 meaning of depth, so the description's restatement of these earns little. It does frame the depth range semantically (tip only vs full chain/genesis budget), but that is largely duplicative of the schema text; baseline 3 applies.

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

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

States a specific verb+resource with scope ('Grounded ChainLock recall at depth 0–5') and explicitly contrasts itself with the two nearest siblings: it is not 'Bayesian rank' and not 'tip-only'. An agent can distinguish it from memory_recall and chainlock_tip without opening either schema.

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

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

Gives explicit when-to-use ('when you need stamped facts from the local vault') and when-not (adaptive memory ranking, reading only the live tip), naming the alternative tools to use instead. This is the full when/when-not/alternatives pattern.

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 tool overwrites the previous local lockset, refuses empty-vault, omits empty chains, does not write the public ledger, requires confirm=true or dry_run=true for mutation, and that ts never backdates authority. These are substantive behavioral details not implied by readOnlyHint=false or destructiveHint=false.

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 carries distinct, necessary information. It is front-loaded with the core action, then alternatives, then behavioral edge cases and parameter semantics. No filler or repetition.

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

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

For a mutating tool with three optional params, the description covers mutation gating, side effects, edge cases, alternatives, and timestamp semantics. With an output schema provided, no additional return-value detail is needed. The description is fully adequate for correct invocation.

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

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

Although input schema coverage is 100%, the description adds meaningful parameter semantics: ts is described as receipt-only metadata that does not backdate, confirm and dry_run are explained as alternative gates, and their optionality in inputSchema.required is explicitly addressed. This materially helps an agent choose correct parameter values.

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 immediately distinguishes it from 'raw-session close' and 'verify-only'. It also names the artifact it writes (receipts/LOCKSET.json), making the tool's purpose unmistakable and distinct from sibling tools.

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

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

The description gives an explicit when-to-use condition ('when the operator wants a new local lockset over current tips') and a clear when-not-to-use list, naming exact alternatives: chainlock_verify, chainlock_append, and runtime_session_close. This is exemplary 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?

Annotations already declare readOnly, idempotent, non-destructive, non-openWorld. The description adds valuable behavior beyond that: empty chains return ok with tip=null and empty=true rather than a refusal, it does not invent a missing tip, and it discloses that it is a Fabric module and only reads a single card (not full depth recall). These are meaningful edge-case disclosures not available in 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 core routing information is front-loaded, but the description is repetitive: it states 'not depth recall' twice, and mentions 'tip card' / 'one card' multiple times. It is longer than necessary to convey the same content, hurting conciseness without losing correctness.

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, zero-required-param tool with an output schema already present, the description covers the key edge cases (empty chain, no invention, Fabric module nature) and routing. Return values needn't be explained since an output schema exists, and safety is covered by annotations. Nearly complete, with minor redundancy.

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 params enumerated and described, including the alias relationship and the omit-both default. The description repeats the alias and omit-default facts but adds no new syntax or format details beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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: 'Read only the live tip card of one local ChainLock chain.' Explicitly distinguishes from siblings by naming chainlock_recall, chainlock_verify, and memory_get as the tools for other purposes. An agent can route correctly 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?

Explicit when-to-use ('when you need the current tip of a named chain') and when-not ('Do not use it for depth-0–5 grounded recall, LOCKSET verify, or adaptive memory explain') with named alternatives for each excluded case. Also clarifies the omit-c/chain default behavior.

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 read-only/idempotent safety, but the description adds rich traits beyond them: fail-closed semantics, 'do not repair silently', the enumerated break reasons (broken-prev, stamp-hash-miss, tip-drift, missing-godlock-cite), non-writing of the public ledger, and the require_seal failure behavior.

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

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

Dense but front-loaded, with the integrity-check purpose stated first and routing guidance next. Minor redundancy ('Fail-closed' is stated twice and return values are listed despite an output schema) keeps it short of a 5.

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 mutation-adjacent integrity tool with full schema coverage, annotations, and an output schema, the description covers purpose, routing, failure modes, and scope (local only, no ledger writes) completely. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%; the enum chain names and the require_seal semantics are already documented in the schema. The description restates the omit-to-verify-all behavior and require_seal fail-closed rule but adds no syntax or format detail beyond what the schema provides, so the 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?

Specific verb (confirm/verify) plus resource (ChainLock chains and LOCKSET), and it explicitly states what it is not: 'Integrity check — not a new seal.' It names its siblings chainlock_append and chainlock_seal, so an agent can distinguish it 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?

Explicit when-to-use ('when you must prove local chain integrity before trusting a recall'), explicit when-not ('Do not use it for appending a stamp or sealing a new lockset'), and named alternatives (chainlock_append, chainlock_seal). 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 are all false hints (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), so the description carries the full burden. It clearly discloses that the tool writes a ledger tip ('appends an ask/refuse ledger tip (not idempotent)'), does not execute domain software, requires confirm=true or dry_run=true for mutation, and returns a specific result shape. This is rich behavioral context beyond what annotations provide.

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

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

The description is dense and front-loaded with the core purpose, but it is a long single paragraph that mixes gate semantics, runtime identity, ledger behavior, and module-wrapper internals. Phrases like 'Named wrapper — same DecisionGATE kernel; not the full MASTER-33 hop list; Softwares exec stays fraggate_call' add differentiating detail but are cryptic and could be trimmed or structured for better scannability.

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 (8 optional params, mutation guards, ledger writes, gate evaluation), the description covers all essential decision axes: when to use, when not to use, side effects, mutation requirements, and return values. An output schema exists, so the returns need not be fully spelled out, but the description still names key outputs (gate view, final_state, ledger_tip, result) and the caller identity constraint.

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 schema already documents each parameter and even contains notes like 'Missing evidence can fail a gate' and the confirm/dry_run behavior. The description adds a few clarifications ('All proposal fields are optional', 'Empty {} still runs the five gates'), but these largely mirror the schema. No significant additional parameter meaning is provided.

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: 'Run the named DecisionGATE five sequential gates on a proposal' and immediately clarifies the scope ('without executing a catalog product'). It differentiates itself from siblings by explicitly naming fraggate_call and library_lookup as the alternatives for execution and search, so an agent can select this tool unambiguously.

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 and when-not-to-use guidance: 'Use this when you want a gate check without executing a catalog product verb. Do not use it for executing a product op or searching the library; use fraggate_call or library_lookup instead.' It also notes the automatic invocation inside fraggate_call, which is a valuable context signal for avoiding redundant calls.

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

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

With annotations already declaring readOnlyHint=false and openWorldHint=true, the description adds substantial context: operation-dependent side effects (read, write, or refuse), open-world reach conditional on the target op, specific refusal codes (FG-HALLUC-TOOL, FG-STUB, FG-LOCAL-ONLY, FG-GATE-REFUSE, FG-LAMB-REFUSE), the confirm=true / dry_run=true mutation gate, and the return envelope fields. No contradiction with annotations; in fact it calibrates the openWorldHint by noting many ops stay isolate-local.

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, but the description is severely bloated. 'UI aliases forward to catalog ops' is stated three times in different forms, the full 40-slug catalog plus five per-product allowlists are dumped inline even though the description itself directs agents to fraggate_list for discovery, and sentences like 'Not the full FragGate door' and 'Empty fraggate_list is discovery (hashed LIVE_OPS)' are out-of-place. The 16-stage pipeline chain (CallEnvelope → FragGate → ... → Return) is opaque jargon that occupies space without actionable guidance.

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 7-parameter tool with nested objects and a mutation gate, the description is genuinely comprehensive: when to use, exclusions, side effects, refusal codes, mutation requirements, alias forwarding, and the return envelope are all covered. It falls short of 5 because the catalog dump is redundant with the tool's own discovery guidance, and the scattered asides ('Not the full FragGate door', 'Empty fraggate_list is discovery') muddy rather than clarify.

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 non-obvious parameter behavior beyond the schema: the reserved top-level key list (name/slug/product/tool/op/verb/claim/proposal/ground/payload/session_id/id) with all leftover keys becoming the payload when payload is omitted, the UI-alias-to-catalog-op forwarding, and the confirm vs dry_run trade-off. The 40-slug catalog enumeration is more contextual than semantic, which keeps this from a 5.

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

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

The description opens with a specific verb+resource statement: 'Execute a known catalog slug+op through the FragGate single door,' and frames it as 'Default exec path — not discovery and not a raw session.' It explicitly names the siblings it is not (fraggate_list, fraggate_describe, runtime_run, runtime_session_exec), so an agent can distinguish it without opening schemas.

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

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

Provides explicit when-to-use ('Use this when fraggate_list and fraggate_describe already identified a live allowlisted op'), when-not-to-use ('Do not use it for discovering names, inspecting one capability without exec, or raw session plumbing'), and names the exact alternatives for each excluded case. 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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds substantial value beyond that: the refusal code FG-HALLUC-TOOL on unknown/missing input, the FG-STUB classification for wipe/unlock on embryolock, and the LIVE+bound state of AZChat with mesh default off.

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

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

Front-loaded with the core purpose and the not-this routing, then constraints, then return shape. Dense but every sentence carries routing or behavioral information. Slightly overpacked with domain classification (embryolock, AZChat) that borders on noise for a generic agent, but none of it is 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?

Output schema exists so return values need not be re-explained, yet the description still names the card fields. Combined with the refusal semantics, the stub/live distinctions, and the name/slug equivalence, an agent has everything needed to invoke correctly or route elsewhere.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a real semantic detail the schema does not carry as prominently: pass name OR slug, one is enough, and combined name/op forms like foldlock/fold-preview are parsed. It correctly avoids restating the enum-less parameter definitions.

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) and resource (one known FragGate card) with explicit scope (live vs stub vs local_only, public ops, engine_digest). Immediately distinguishes itself from siblings by naming exactly what it is not (not execute, not digest-only proof) and listing the four alternative 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?

Explicit when-to-use ('when you already have a name or slug from fraggate_list or GET /v1/software') and explicit when-not with a named alternative for each excluded case (fraggate_list, fraggate_verify, runtime_pull, fraggate_call). Prerequisites and refusal behavior (FG-HALLUC-TOOL) are also 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds vital behavioral context: it never enables mesh radios, never invents tools/ops, returns registry entries/digests/allowlists, and calls out that unknown names will refuse with FG-HALLUC-TOOL. It also clarifies that compact LIVE_OPS tokens are discovery hints, not execution.

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 includes large embedded allowlist catalog listings that could arguably live in an output schema or reference doc. However, those listings serve the tool's discovery mission and the front-loading is good ('List the hashed FragGate registry... Discovery first'). It earns its length functionally, though it is not tightly 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 discovery purpose and the presence of an output schema plus thorough annotations, the description covers usage boundaries, return contents, and key safety traits. It could be considered slightly over-complete for a simple 0-param tool, but it leaves no operational hole for an agent deciding how to invoke it.

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

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

The schema already covers the only parameter (none, empty object) with a description, so the baseline is high. The description further reinforces that 'Empty {} only' and explains what the caller should expect, adding a small but meaningful behavioral constraint 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 states a specific verb ('List') and resource ('the hashed FragGate registry') and distinguishes itself from siblings like fraggate_describe and fraggate_call. It explicitly frames itself as 'Discovery first' and gives the scope (live / stub / local_only + digests), which clearly differentiates it from other 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 explicit when-to-use and when-not-to-use guidance, naming alternatives (runtime_software, fraggate_describe, fraggate_call) and specific exclusions ('Not a hub Software tab and not exec'). It also explains the discovery-first role, which leaves no ambiguity about selecting this tool.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral detail beyond them: empty {} refuses FG-HALLUC-TOOL, unknown names refuse, digest-only compares the whole registry hash (kind=registry), name/slug compares that entry (kind=entry), and mismatch returns ok=false with matched=false rather than inventing a digest.

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

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

Front-loaded with purpose, then usage, then behavior, and most sentences earn their place. Slightly repetitive: 'Not an exec path and not a describe card' restates the earlier exclusions, and the closing return-value sentence duplicates a present output schema.

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

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

Complete for a zero-required-param verification tool with an output schema: it covers refusal behavior, the two comparison modes, and match/mismatch outcomes. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds combination semantics the schema does not fully state: name or slug alone is enough, name+digest must equal that card's engine_digest, and the digest pattern is 64-hex. This is meaningful Fn semantics beyond the field docs.

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 (Confirm/verify) and resource (name, slug, or 64-hex engine_digest against the FragGate registry), and immediately frames it as 'a proof, not a card listing', which separates it from the sibling describe/list tools. An agent can distinguish it from fraggate_list, fraggate_describe, and fraggate_call 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 says when to use it ('when you must prove a listed name or digest exists after fraggate_describe') and when not to ('Do not use it for listing the registry, describing ops, or executing'), naming the three alternatives. Routing conditions for digest-only vs name/slug are also spelled out.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavior beyond that: empty q does not fabricate a cite, unknown ops return FG-UNKNOWN-OP, this is a named-corpus wrapper rather than MASTER-33, extra keys are forwarded as payload, and the response is returned inside a display envelope. These are meaningful operational details not inferable from 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 front-loaded with the core purpose and uses a logical flow: what, when, not-for, error behavior, and payload behavior. It is dense but slightly redundant, e.g., 'Not a private-file search engine and not AKM/ChainLock' partially repeats earlier exclusions. Still, nearly every sentence adds needed differentiation.

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 2 optional parameters, no required inputs, full schema coverage, a rich output schema, and a large sibling set, the description is exceptionally complete. It covers defaults, error responses, payload forwarding, return payload types, and limitations, making it fully usable by an agent without further investigation.

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 per-property descriptions, so the baseline is 3, but the description adds real semantic value: q is explicitly differentiated from memory_recall q and ChainLock q, op's default is clarified ('Omit op to search'), and extra keys beyond q/op are described as riding along as aziel-corpus payload. These are distinctions an agent needs to call the tool correctly.

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

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

The description opens with a specific verb and resource: 'Search the public Aziel Digital Library (aziel-corpus search / example / skill)'. It also immediately states what the tool does NOT return ('cites, not beliefs and not vault stamps'), which differentiates it from related memory and ChainLock tools without needing to open 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?

It explicitly states when to use the tool: 'Use this when you need a public corpus cite, example record, or library skill.' It also gives a clear exclusion list and names the alternatives: memory_recall, chainlock_recall, and fraggate_call slug=aziel-corpus. 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.

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

Annotations only provide basic hints; the description adds substantial behavioral disclosure: it writes a forward-only RoseClock LEARN stamp, states 'Posterior ≠ truth', 'authorizes_action=false', 'No automatic MODEL_UPDATE', and clarifies the confirm/dry_run mutation gate. These are meaningful traits beyond the schema and annotations, with 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?

Front-loaded with purpose, and every sentence carries information. However, some redundancy exists: 'subject or memory_id recommended' and 'Mutation requires confirm=true or dry_run=true' appear in both the description and the input schema, which adds slight repetition in an otherwise dense definition.

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

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

For a tool with six optional parameters, a mutation gate, exclusions, and an output schema, the description covers usage, alternatives, behavioral caveats, parameter interpretation, and return fields ('triad_score, omitted leg, posterior, effective N, and Brier notes'). 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%, so baseline is 3. The description adds valuable nuance: 'subject or memory_id recommended', 'use_case labels calibration; it is not a permission', and the subtle 'confirm and dry_run stay optional on inputSchema.required' runtime distinction. This is helpful above the schema descriptions.

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

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

States a specific verb and resource ('Calibrate one memory'), names the exact algorithm (3-of-4 triad plus Bayesian posterior, AKM-TRIAD-1.0), and distinguishes itself from ranked search and explain view. It also names sibling tools it is not, so an agent can differentiate 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?

Explicitly says when to use it ('when an observed memory should receive a posterior after evidence') and when not to ('Do not use it for observing a new fact, resolving an outcome, or explaining a stored node'), with direct alternatives (memory_observe, memory_resolve, memory_get). 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 cover the read-only/idempotent/non-destructive profile, but the description adds substantial context beyond them: refusal code AKM-NOT-FOUND for missing/unknown ids, 'authorizes_action stays false', the append-only nature of the node, and the belief_is_not_truth return caveat. This is rich behavioral disclosure.

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

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

Front-loaded with the core action and scope, and sentences generally earn their place. However, the alias point ('Pass memory_id or id — one is enough; they are aliases') and the view semantics are each restated, adding some redundancy for a 3-parameter getter.

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 tool with full schema coverage and an output schema, the description is more than complete: it explains error behavior, aliasing, view semantics, and safety flags. 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 coverage is 100%, so baseline is 3, but the description adds real meaning: memory_id and id are aliases for one record (not two), 'subject is not a lookup key here', and concrete view semantics (history = events/resolutions; calibration = posterior/triad/Brier). It goes beyond the schema descriptions.

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

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

States a specific verb (read/explain) and resource (one memory's stored explanation) with explicit scope qualifier '— not a ranked list.' It names the views it returns (node/history/calibration) and clearly differentiates from memory_recall and memory_observe.

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 ('when you have a memory_id and need the stored explanation') and when-not ('Do not use it for ranked adaptive recall or appending an observation'), naming the alternative tools. Also notes 'There is no memory_delete' to redirect any deletion intent.

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 provide flags (readOnly=false, etc.), so the description carries the full burden. It discloses mutation requirements (confirm=true or dry_run=true), append-only nature (no memory_delete), the fact that authorizes_action stays false, and the epistemic caveat ('Posterior ≠ truth'). It also explains runtime gates. This goes well beyond the minimal flag information and sets accurate 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 dense but every sentence adds value: action, usage, behavioral caveats, mutation gates, and returns. It is front-loaded with the primary action. While slightly long, it avoids redundancy and is well-structured for an agent to parse quickly.

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 (mutation, confirmation, multiple siblings), the description covers the core operational aspects: when to use, how to mutate, what it returns, and the belief-vs-truth caveat. It does not detail error scenarios or rate limits, but these are not critical for correct invocation. The output schema likely covers return structure, so that gap is acceptable.

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 each parameter described. The description adds clarity on the confirm/dry_run interaction (optional in schema but required for mutation) and explains the purpose of use_case ('Not a truth claim') and the behavior of hash-only cards with fact. It adds contextual meaning beyond the raw parameter names and types.

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 ('Append the first memory_observation to the ChainLock learn chain') and immediately differentiates from siblings by naming chainlock_append, memory_resolve, and memory_recall. It clearly states this tool is for observing a new fact before resolve/calibrate, leaving no ambiguity about its role.

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

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

It explicitly states when to use ('Use this when you have a new fact to observe before resolve/calibrate') and when not to use, listing 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 model 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 read-only/idempotent/non-destructive, but the description adds substantial non-obvious behavior: it does not authorize action, posterior rank is not truth, failed verify refuses CHAIN_VERIFY_FAIL without inventing cards, empty grounded recall returns no-stamp, and ranking is capped at 16 cards. These are exactly the failure-mode and safety traits 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 routing and constraints are front-loaded, but the text is repetitive — "Belief list — not raw grounded stamps..." is restated almost verbatim in the next sentence. Several sentences could be merged without loss, and the jargon-dense framing slows scanning.

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

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

For a 4-param tool with full schema coverage and an output schema, the description covers behavior, routing, failure modes, and defaults thoroughly. It arguably over-explains the return shape (count, facts, belief_is_not_truth) that the output schema already provides, 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: q is lexical rank text (not a SQL filter) and empty q still verify-then-ranks, depth omitted defaults to 5 unlike chainlock_recall's default of 1, use_case weights triad_fit and is not a permission, and limit clips the already-capped list. This goes beyond the schema text.

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

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

The description names a specific operation (ranked adaptive recall of a belief list after ChainLock verify) and explicitly distinguishes itself from siblings chainlock_recall, library_lookup, and memory_get. The core purpose is identifiable, though heavy jargon ("AKM-TRIAD-1.0", "grounded stamps") adds noise without adding precision.

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 want a ranked belief list after verify") and explicit when-not 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"). Routing is unambiguous.

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

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

The description goes well beyond the annotations (readOnlyHint=false, idempotentHint=false) by disclosing that it appends an additive resolution stamp, does not rewrite history, refuses with AKM-NO-MEMORY when memory_id/subject is missing, and treats dry_run as a no-write preview. This adds meaningful behavioral context that annotations alone do not convey.

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

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

The description is dense and front-loaded with the core purpose, then usage, then constraints. It has minor redundancy ('Does not rewrite history' and 'Does not rewrite prior observations' appear twice), but every part still contributes needed guidance; the repetition is a small cost against the strong structure.

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 (8 parameters, mutation gate, error conditions, distinct UNKNOWN/MISS states), the description covers requirements, error responses, alternative tools, and preview behavior. An output schema exists, so return details are not necessary, and nothing essential is missing for an agent to invoke this correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable semantics beyond the schema: it clarifies the outcome omission means UNKNOWN, the mutual exclusivity/requirement of memory_id or subject, and the interplay between confirm and dry_run. It does not restate each parameter but provides higher-order usage meaning, justifying 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?

The description states a specific verb ('Append') and resource ('memory_resolution outcome on an already-observed memory'), and explicitly distinguishes this tool from siblings by naming 'No memory_update — this is the forward outcome path.' It clearly differentiates from memory_observe, memory_calibrate, and memory_get within the same description.

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 conditions ('Use this when an observed memory_id or subject now has an outcome') and when-not-to-use alternatives ('Do not use it for first observation, calibration, or reading history; use memory_observe, memory_calibrate, or memory_get instead'). It also explains the mutation gate with confirm=true or dry_run=true, leaving no ambiguity about prerequisites.

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

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

Annotations only declare flags (readOnlyHint=false, etc.) without behavioral detail. The description supplies rich context: it stores a hash receipt only, does not accept video bytes, keeps the file with the operator, and has distinct refusal codes (MESH-BAD-INPUT, MESH-NO-PUBLISH). It also explains the mutation gate (confirm=true or dry_run=true) and that dry_run never writes, going 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 front-loaded with the core purpose, but it is long. Most sentences contribute unique information—exclusions, error behavior, and gating semantics—so the length is justified for a tool with nontrivial safety constraints. Slight redundancy with schema text (e.g., parameter labels) prevents a 5.

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 5-parameter schema, 100% schema coverage, output schema, and the complexity of mutation gating, the description covers every behavioral corner an agent needs: what happens on invalid input, publish-shaped keys, dry-run behavior, and explicit alternatives. Nothing required for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds meaningful meta-semantics beyond the schema: sha256 is required and 64 hex, title and product are 'labels, not file contents,' and confirm/dry_run are intentionally optional in inputSchema.required yet enforce a runtime mutation gate. This exceeds the baseline while not being strictly necessary.

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: 'Register the SHA-256 of a local file as a hash receipt' and immediately clarifies 'never a publish or upload path.' It clearly distinguishes this tool from publishing, uploading, mailing, and mesh joining, matching the title 'Register a local hash receipt.'

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 an explicit when-to-use condition: 'Use this when the operator already holds a local file and wants only its hash recorded.' It then lists what not to use it for and names concrete alternatives: 'use local qnm-node/ anon-broadcast loopback, AZMail via fraggate_call, or mesh_join instead.' This is complete routing guidance with 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?

Beyond the readOnly/idempotent/non-destructive annotations, it discloses concrete behavioral guarantees: no tethers drop, no implicit heal, no account resurrection, no wipe internals, and that repeating the call still refuses. It also names the exact returned marker (MESH-DISABLE-REFUSED with enabled=true), which goes well past what the annotations carry.

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 opening sentence is front-loaded and clear, but the text is dense and repetitive: suite-presence 'stays ON' is stated twice, refusal is restated three times, and the AZMail product-local note is a tangential aside. The content is useful but not tightly trimmed.

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

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

With an output schema present and zero parameters, the description covers everything an agent needs: what it does, when to call it, what it does NOT do, and the identity of the refusal marker. No gap remains that would cause a misinvocation.

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, so the baseline is 4; the schema itself already states 'No arguments. Send {}.' The description adds no parameter detail, which is correct since none exist.

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 resource and effect: it confirms read-only QNM suite-presence stays ON and returns MESH-DISABLE-REFUSED rather than disabling anything. The verb/resource pairing is slightly inverted from the tool name (mesh_disable actually refuses to disable), but the text explicitly corrects this with 'not a kill switch' and distinguishes it from mesh_leave and mesh_enable.

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 when ('when a client still posts the historical disable route and needs the honest refuse') and an explicit when-not with named alternatives ('Do not use it for dropping one node or declaring an extra bearer; use mesh_leave or mesh_enable instead'). Routing between siblings is unambiguous.

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

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

The description goes well beyond the annotations by disclosing that the operation 'stores the bearer,' is rate-limited, refuses empty and reserved names, and does not arm, wipe, heal, or resurrect accounts. It also clarifies the mutation gate: 'Mutation requires confirm=true (runtime gate) or dry_run=true (preview only, no write).' No contradiction with annotations exists.

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

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

The description is well organized and effectively front-loaded, but it is somewhat repetitive: 'bearer is required' appears in both the description and schema, and 'not a login mesh' plus the reserved-name refusal appear in both the description and the bearer parameter description. Tighter wording would be more efficient.

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 presence of an output schema, the description does not need to explain return values, yet it still mentions them briefly. It covers use cases, non-use cases, failure conditions, reserved names, mutation requirements, and side effects, making it complete for an agent to call correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful parameter semantics by explaining that bearer is required, that confirm and dry_run are optional in the schema yet required as a runtime mutation gate, and that login/account/gate names are refused. This adds value beyond the raw schema.

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

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

The description states a specific verb and resource: 'Declare an extra QNM suite bearer (POST /v1/mesh/enable)' and immediately clarifies it is 'additive presence, not a first-time on-switch.' This clearly differentiates mesh_enable from the sibling tools such as mesh_status, mesh_join, and mesh_nodes.

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 the tool: 'Use this when an operator wants to declare an additional bearer on top of the default-on rollup.' It also gives explicit exclusions and alternatives: 'Do not use it for reading status, joining one node, turning suite-presence off, or logging into an account; use mesh_status, mesh_join, or mesh_nodes instead.' This leaves little room for 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses concrete behavioral traits: the refresh is not idempotent, a missed 5-minute window drops the node, radios-off refuses MESH-OFF, expired node_id refuses MESH-UNKNOWN-NODE with no account resurrection, mutation requires confirm=true or dry_run=true, and various body/equivocation/heal refusals. This is rich, specific behavioral context.

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

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

The description is long but densely informative, with purpose and usage front-loaded in the first two sentences. The later sentences cover refusal conditions and mutation gates that are essential for correct invocation, so they earn their place. Some domain jargon ('Split the wires', 'REHEAL', 'armed neighbor_heal') is unexplained, which slightly reduces clarity, but the overall structure is logical and purposeful.

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 6 parameters, critical mutation semantics, and a complex refusal-code surface, the description covers everything an agent needs to invoke it correctly: prerequisites, alternatives, mutation gates, per-parameter constraints, and failure behavior. An output schema exists, so the absence of a return-format explanation 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 description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: node_id comes from mesh_join, presence replaces the live|locked|isolated class, tip_hash is on the fast tick with no body, and same prev plus two tips causes MESH-EQUIVOCATION. It also clarifies that confirm/dry_run remain optional in the schema but are runtime-required for mutation, which materially improves parameter understanding.

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: 'Refresh one existing node's 5-minute QNM TTL (POST /v1/mesh/heartbeat) — not a first join.' This clearly distinguishes it from the sibling tools mesh_join and mesh_leave by explicitly saying what it is not, so an agent can select it correctly without opening the schema.

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

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

The description gives explicit when-to-use guidance: 'Use this when you already have a node_id from mesh_join and transmission radios are LIVE.' It also names exclusions and alternatives: 'Do not use it for first-time registration or dropping the node; use mesh_join or mesh_leave instead.' This fully covers the selection decision.

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?

Description reveals mutation semantics ('Write: additive presence with a strict 5-minute TTL'), counting rules for live/locked/isolated nodes, the software_nodes caveat, error codes (MESH-OFF, MESH-BAD-INPUT), and the confirm/dry_run gate. Annotations only provide hint flags (readOnly=false, etc.), so this content adds substantial behavioral context beyond 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 long and information-dense, but front-loaded with purpose and usage before behavioral details. Every sentence contributes necessary context for a complex tool, though the density sacrifices some readability.

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

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

Covers purpose, usage, behavioral quirks, error modes, parameter semantics, mutation requirements, and return fields (node_id, presence, presence_ttl_ms). With an output schema and 100% parameter coverage, nothing essential is missing for an agent to invoke this correctly.

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

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

Schema already documents all parameters (100% coverage), and the description adds the crucial confirm/dry_run mutation gate and the default for presence. However, it mostly restates schema constraints (node_id pattern, product required), so value added beyond schema is moderate.

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 ('Register'), resource ('one product node into QNM rollup'), and explicitly distinguishes it from a TTL refresh ('first presence, not a TTL refresh'). It also names sibling tools for alternative operations, so an agent can tell it apart from mesh_heartbeat or mesh_enable.

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 the condition for use ('when transmission radios are LIVE and a catalog product should appear in live/locked/isolated counts') and lists exclusions ('Do not use it for refreshing an existing node...') with named alternatives (mesh_heartbeat, mesh_nodes, mesh_enable, runtime_session_open). This is textbook when/when-not guidance.

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

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

The description discloses behaviors beyond annotations: 'Destructive to that node's presence only', 'No implicit heal', 'Repeating a missing node_id is a no-op/refuse', and the confirm/dry_run runtime gate. These add practical context that annotations (destructiveHint, idempotentHint) do not fully convey. 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 dense but well-structured, starting with purpose, then usage, then behavioral details, parameter gates, and return. Each sentence earns its place, though it is slightly long. It is appropriately sized for a mutating tool with gates.

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?

It covers purpose, usage exclusions, edge cases (missing node_id), confirmation requirements, dry_run preview, and return receipt. With an output schema present, it need not detail return structure. This is complete for safe and correct invocation.

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

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

While schema coverage is 100%, the description adds essential semantics: it clarifies that node_id is required, explains the runtime gate requiring confirm=true or dry_run=true, and notes that confirm and dry_run remain optional in the schema despite being required for mutation. This is critical for correct invocation and goes beyond schema descriptions.

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

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

The description clearly states 'Drop one node from the QNM rollup' with a specific verb and resource, and distinguishes it from 'a suite-wide radio off'. It also names alternatives (mesh_nodes, mesh_status) so the agent can differentiate it from sibling tools.

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

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

Explicit guidance: 'Use this when a previously joined node should leave the counts' and 'Do not use it for turning suite-presence off or listing nodes; use mesh_nodes or mesh_status instead.' This provides direct when-to-use and when-not-to-use conditions with named alternatives.

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 the safe read-only, idempotent profile, so the bar is lower. The description still adds real behavioral context: a 5-minute TTL and presence classes on nodes, plus scope exclusions. Minor deduction because some clauses ("Views/MCP/downloads do not enter QNM-S") are cryptic rather than clarifying.

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

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

Front-loads the core purpose and the "not suite totals" qualifier before usage and exclusions. Mostly second sentence earns its place, but the terse fragments "No scores. No leaderboard." are slightly redundant noise that dilute the signal.

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 explanation, and annotations carry the safety profile. The description supplies the purpose, usage routing, and scope constraints an agent needs to invoke this zero-argument 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?

Zero parameters, which is the baseline-4 case. The schema itself explains "No arguments. Send {}." and the description correctly adds nothing about parameters, so there is no gap to compensate for.

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 ("List the QNM node roster") and enumerates the returned fields (node_id + presence + TTL) while explicitly excluding suite totals. It names the siblings it is not (mesh_status, mesh_join, mesh_leave), so an agent can distinguish it 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 explicit when-to-use ("after mesh_status", when you need the current node list) and when-not-to-use with named alternatives ("use mesh_status, mesh_join, or mesh_leave instead"). This is the full when/when-not/alternatives pattern.

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 reinforces them with 'Read-only' and 'Never enables radios beyond default suite-presence.' It adds important non-obvious context: this is not a login mesh, Views/MCP/downloads do not enter QNM-S, the node process is local qnm-node/, and it is not a second Softwares door. 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 core purpose and usage guidance are front-loadedheavily, but the description becomes a dense run-on of system-specific caveats such as 'Kernel-direct fabric wrapper — not MASTER-33; not a second Softwares door' and 'Views/MCP/downloads do not enter QNM-S.' It repeats read-only and radio-enabling statements and mixes return-value enumeration with architectural disambiguation, so it is more verbose 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?

Despite its verbosity, the description is complete for selection and invocation: it explains what fields are returned, gives the live_nodes formula, names the QNS-CD-1.0 citation, states the no-argument contract, and covers exclusions. An output schema also exists, so the agent is not missing any needed context.

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 rentals and the schema already states 'No arguments. Send {}.', so there is no parameter-level detail for the description to add. The baseline of 4 for a no-parameter tool is appropriate, and the description does not need to compensate for any schema 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 opens with a specific verb and resource ('Read QNM suite rollup totals') and immediately defines the key fields (live_nodes, software_nodes, bearers, etc.). It explicitly says this is 'not the node roster' and names mesh_nodes as the sibling to use for listing individual nodes, making its scope unmistakable.

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

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

It gives explicit positive guidance: 'Use this when you need public Live Nodes (mesh size) or software_nodes (product Worker roster).' It also provides clear negative guidance with named alternatives: 'Do not use it for listing individual nodes, enabling extra radios, or executing a catalog engine; use mesh_nodes, mesh_enable, or fraggate_call 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds scope boundaries the annotations do not carry — that this is a URL-bootstrap-only helper that does not touch Software-tab cards or the hashed registry — though it says nothing about auth or rate limits.

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

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

Front-loaded with the core purpose and well ordered (what, when, when-not, alternatives). However, 'compact bootstrap', 'This helper is URL bootstrap only', and 'Returns compact product list with skill URLs' restate the same point three times, so it is slightly redundant.

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-value explanation is optional (though the description supplies it redundantly). Routing to alternatives is complete; the only gap is the absence of any note about response compactness limits or invocation constraints, which is minor for a no-arg read.

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-parameter tool, so the baseline is 4; there is nothing for the description to disambiguate. The schema's own 'No arguments. Send {}.' note already covers invocation, and the description adds no param detail beyond restating the bootstrap nature.

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 ('Read a compact bootstrap of every product skill URL and invoke prefix') and explicitly negates two sibling scopes (Software-tab cards, hashed registry). An agent can identify what it returns and what it does not 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?

Explicitly names when to use it ('when a client needs skill URLs in one shot'), when not to use it (Software-tab refresh, hashed registry discovery, exec), and routes to the correct alternatives (runtime_software, fraggate_list, fraggate_call). This is a complete routing statement.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, lowering the bar, and the description usefully adds scope limits (“Does not list hub cards or execute”) plus the [advanced/internal] positioning. It does not add much beyond that, but the extra scope disclosure is genuine value over the structured fields.

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

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

The [advanced/internal] tag is well front-loaded, but the text is repetitive: door=fraggate and registry_digest appear twice, and the human-how-to exclusion is restated as both “not the human how-to” and “not the default agent path.” Several sentences could be merged without losing meaning.

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 explained, and the annotations carry the safety profile. The description covers purpose, alternatives, and scope limits well; only the redundancy keeps it from being fully tight.

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 0 parameters, so the baseline is 4; schema coverage is 100% and the description correctly signals no arguments are needed. There is no parameter semantics to add.

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 the machine runtime manifest JSON”) and enumerates the returned contents (version, role, door=fraggate, engine slugs, registry_digest). It explicitly distinguishes itself from the human how-to skill and names related siblings, so an agent can separate it from peers 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 explicit when-to-use (“when a client needs the machine manifest rather than the human skill”) and when-not (“Do not use it for the default agent how-to or hashed registry discovery”), naming the alternatives runtime_skill and fraggate_list. Routing is unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond that: unknown slug throws 'unknown product' rather than inventing a card or emitting FG-HALLUC-TOOL, and a missing skill falls back to in-repo markdown. It also clarifies extra keys are ignored and are not an op payload.

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 routing constraint is front-loaded, but the text is redundant: 'not FragGate live/stub status' and 'not exec' are each stated twice, and the return-field list duplicates the output schema. It earns its size only partially.

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 and full annotation coverage, the description need not explain return values, yet it still covers the routing decision, error behavior, and fallback semantics. 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 description coverage is 100% and the schema already documents slug, the product alias, and that extra keys are ignored, so the baseline is 3. The description largely restates the alias/required semantics rather than adding new meaning, though the 'not an exec path' note is mildly useful.

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 ('Open one hub product card by slug') and enumerates the card fields (name, version, skill, download, ops). It explicitly contrasts itself with the FragGate status siblings and with exec, so an agent can distinguish it 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 trigger ('when you already have a slug from GET /v1/software or fraggate_list'), explicit exclusions (do not use for FragGate live/stub status or executing an op), and names the alternatives fraggate_describe and fraggate_call for those cases.

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 side-effect dependency, that this is not a backdoor past FragGate, that a session auto-opens when session_id is omitted, and that mutation requires confirm=true or dry_run=true. These details meaningfully extend the annotations, which only say readOnly=false and openWorld=true.

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: identity, conditions of use, exclusions, side-effect warning, session semantics, payload rule, mutation gate, and return envelope. The most important routing information is front-loaded.

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 internal exec tool, the description covers the non-obvious semantics: DecisionGATE admission, open-session behavior, confirm/dry_run gating, extra-key payload handling, and the output envelope including refusal. With a rich schema and output schema present, nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds useful emphasis on extra keys being treated as payload and confirm/dry_run enforcement, but it largely restates what the input-schema descriptions already provide.

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

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

The description opens with a concrete verb and resource: 'admit a slug+op ... and run it through a raw session.' It immediately labels the tool as an advanced/internal façade, distinguishing it from the default exec path, and explicitly names fraggate_call and runtime_session_exec as 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?

Usage is fully specified: use only when explicitly asked for the raw runtime_run path; do not use for the default agent exec path or an already-open session. It names the correct alternative tools for those cases and adds rules about session_id, confirm, and dry_run.

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