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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real value beyond them: the mechanism (destroying the wrapped key) and the consequence (unreadable to everyone, operator included). That is exactly the kind of context an agent needs before an irreversible call.

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?

Four tight sentences with the destructive intent and irreversibility front-loaded before the mode variant. Slight redundancy with the schema on the warmStart branch and the trailing "its key first" is a touch cryptic, keeping it from 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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile. The description covers mechanism, consequence, reversibility, and the dual memory/snapshot mode, leaving nothing an agent needs 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 description coverage is 100%, so the baseline is 3, and the schema already documents the warmStart="delete" branch, id format, and token pattern in more detail than the description. The description restates the mode switch but adds no syntax or format detail beyond the schema.

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

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

States a specific verb+resource ("cryptographically erase one memory by its cell id") with the GDPR framing that pins the intent. An agent can distinguish it from siblings like saihm_revoke_share or saihm_remember 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 and when-not ("use it when erasure is the intent, not to tidy a working set"), plus a clear branch for the snapshot mode. It does not name a concrete alternative tool for unsharing/tidying, so it stops short of full routing guidance.

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

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

Annotations indicate it is not read-only (readOnlyHint=false), but the description adds crucial behavior: the tool is a stub and will return a 'governance unavailable' error. This goes beyond the annotations and sets correct expectations for the agent's action. No contradiction.

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

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

Two compact sentences front-load the main purpose and conditional parameters, then immediately note the limitation. No wasted words, and the critical caveat is placed at the end without obscuring the primary intent.

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 conditional parameters and non-functional status, the description covers every piece an agent needs: which scope is required, what extra parameters are needed for each scope, and the exact failure behavior. It is complete and self-contained.

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 paramKey's schema description already mentions 'when scope=emission_param'. However, the description also clarifies that proposedValue is also conditional on emission_param, which the schema does not explicitly state. This adds meaningful conditional logic beyond what is in the schema.

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

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

The description opens with a specific verb ('open') and a clear resource ('protocol governance proposal'), and distinguishes its function from the sibling vote tool. It explicitly states the two scopes and the conditional parameters, and even clarifies the current non-functional state, so an agent knows exactly what the tool is meant to do.

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 instructions: set scope to 'emission_param' or 'protocol_upgrade' and, for 'emission_param', also pass paramKey and proposedValue. It also explicitly warns the tool is not enabled and will return an error, effectively telling the agent not to rely on it. This is clear and complete.

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

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

Discloses a critical behavioral trait beyond annotations: despite appearing write-oriented, the tool is stubbed and returns a 'governance unavailable' error without recording a vote. This adds important context beyond the readOnly/idempotent/destructive hints.

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

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

Two sentences with no fluff. The primary action is stated first, and the critical unavailable-error behavior is front-loaded in the second sentence before any unnecessary detail.

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

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

For a simple two-parameter tool with full schema coverage, the description fully covers invocation, parameter semantics, and the actual behavioral outcome. No output schema exists, but the description explicitly discloses the error response, 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?

Input schema coverage is 100%, with both proposalId and approve documented. The description restates the approve true/false semantics and ties the action to proposalId, but adds little beyond what the schema already provides.

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

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

States a specific verb and resource: cast a vote on an open protocol governance proposal by proposalId. It clearly differentiates the voting action from the sibling propose tool and explains the approve semantics.

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?

Clearly indicates that casting a vote is the intended action and that governance is not enabled, so calling the tool will return an error rather than succeed. It does not explicitly name alternatives, but the purpose and current non-functional status make appropriate usage 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 only declare the mutation/idempotency/open-world profile; the description adds substantive behavior: it self-generates a sovereign memory key on-device, triggers a one-time human approval returning a URL and short code, completes asynchronously without a second call, and involves no payment. This is exactly the extra context annotations cannot 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?

Front-loaded with the core action, then branches into the two do-not-join cases and the approval mechanics. Well organized, though 'the join finishes by itself' and 'there is no need to call saihm_join again' are mildly 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?

With no output schema, the description covers the return value (URL plus short code), the post-approval state (memory tools work), and the no-payment guarantee. An agent has everything needed to call this correctly and to tell the user what to expect.

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

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

Schema coverage is 100% and the single parameter's schema description already spells out the confirmation precondition. The description's 'Pass newIdentity: true once they confirm' restates rather than extends the schema, so the 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 and resource: 'Activate free SAIHM persistent memory for this agent.' It is immediately distinguishable from siblings like saihm_remember, saihm_recall, and saihm_status, which operate on an existing memory rather than creating one.

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 the user asks to join, sign up for, or set up SAIHM') and explicit when-not-to-use with alternatives: ask about an existing identity first and route to export-identity, and do not join in fresh hosted/cloud sessions. This is unusually complete routing guidance.

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

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

Annotations already cover readOnly/idempotent/non-destructive, yet the description adds real behavioral content: decryption happens client-side and the server never sees plaintext, the shared-cell path is read-only, warmStart writes a snapshot file that must be read then removed, and sharesOnly returns shares_paging_unsupported on unsupported endpoints. These are side effects and failure modes annotations cannot express.

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

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

Front-loaded with the core purpose and safe-decryption guarantee, then one sentence per mode, so every sentence earns its place across eight branching behaviors. The warmStart sentence is dense and mixes two modes into one clause, which slightly hurts readability for an otherwise well-structured block.

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 annotations carry the safety profile. Given ten optional parameters and a nested sharer record, the description still covers the mutually exclusive modes, the required-argument trios, pagination via after/next, and one error case, leaving nothing an agent needs 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 the baseline is 3; the description exceeds it by explaining parameter interplay rather than restating fields — query is ignored when reading by cellId, and sharerPinnedAgentIdHashHex/sharerRecord/cellId form one required trio. It does not, however, add format or value-level detail beyond the schema.

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

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

States a specific verb and resource (retrieve and locally decrypt your memories) and enumerates the distinct read modes it supports. It is clearly the read path in a family containing saihm_remember, saihm_forget and saihm_share, but it never names a sibling, so the differentiation is implicit rather than explicit.

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 framing ('at the start of a session, or whenever past context is needed') and then routes on argument combinations: query to filter vs omit to load all, cellId alone vs with sharer fields, listOnly, sharesOnly, and warmStart latest/list. Each branch is tied to a condition, which is exactly the guidance an agent needs.

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

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

Annotations already declare write/openWorld/non-idempotent, and the description adds substantial context on top: the encryption model (key never leaves the process, server holds unreadable ciphertext), the share re-issue side effect on updates, and the warmStart snapshot behavior including file removal. This is genuinely useful behavioral disclosure 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 purpose is correctly front-loaded, but the share re-issue clause is a dense run-on ('...they are re-issued for the new version and the result counts them, and a share that was not re-issued needs saihm_share again') that is hard to parse. The warmStart branch is tacked onto the end, making the single paragraph feel overloaded.

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

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

For a 5-parameter tool with two operating modes (content store vs warmStart snapshot), the description covers both modes, the encryption guarantee, and cross-references saihm_forget/saihm_share. With an output schema present it need not detail return values, and it is largely complete, though the update/share interaction remains the least clear part.

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: it explains that cellId switches to update mode, that warmStart 'put' consumes token/coversThrough and stores a snapshot, and how shares interact with updates. It adds value over the schema rather than merely restating it.

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

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

The description opens with a specific verb+resource ('Store information in SAIHM persistent memory') and clarifies the create-vs-update mode via cellId, distinguishing it from the read sibling (saihm_recall) and the delete sibling (saihm_forget). It never explicitly names saihm_recall as the read counterpart, so full sibling differentiation is implied rather than stated.

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?

'Use this when a fact, decision, or piece of context should outlive the current session' gives a clear triggering condition, and it names saihm_share as the follow-up when a share is not re-issued. It lacks an explicit when-not statement (e.g., prefer saihm_recall to read), leaving one 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?

Beyond the annotations, the description adds the critical limitation 'It applies to future reads and cannot retract what the recipient has already read' and clarifies that the memory itself survives. These details meaningfully shape an agent's expectations about side effects and are not present in the schema or annotations. There is no contradiction with 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?

Three sentences with zero filler: the first states the operation, the second discloses the main behavioral caveat, and the third gives the usage alternative. The key action 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 two-parameter tool with no output schema and no nested objects, this description covers the operation, the exact parameter relationship, the temporal limitation, and the sibling tool to use instead. 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 coverage is 100%, so the baseline is 3. The description adds relational meaning by instructing the caller to reuse the same cellId and recipientHex from the original saihm_share call, which is not explicitly stated in the schema descriptions. This small but valuable addition justifies a 4.

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

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

The description states a specific verb and resource: 'Withdraw a grant made with saihm_share'. It clearly differentiates itself from saihm_forget by noting 'the memory itself remains, and saihm_forget is what erases', so an agent can distinguish revoking access from erasing memory without opening schemas.

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

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

The description gives an explicit when-to-use instruction: 'Use it to end access'. It also names the alternative saihm_forget and the condition for erasure, and it tells the agent to name 'the same cellId and the recipient's recipientHex', tying usage to the original grant.

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 non-read-only, non-idempotent, open-world, non-destructive. The description adds genuinely non-obvious behavior beyond that: sharing re-wraps the cell key rather than copying the memory, and exposure is limited to exactly one cell. It does not explain why the operation is non-idempotent or what happens on repeat shares, so it is not a 5.

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

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

Three tight sentences, front-loaded with the action and target, then recipient identification, then scope, then the exposure/key-wrap caveat. Every sentence carries distinct information with no filler.

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

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

For a mutation tool with a nested recipient object and no output schema, the description covers the security model and exposure limits well. It omits success/failure behavior, permission requirements on the caller, and any mention of expiryEpoch, which the schema carries but the narrative does not.

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 every parameter including the tricky expiryEpoch hour-encoding. The description restates cellId, the scope values, and the out-of-band pinning requirement, adding intent but little syntax or format detail beyond the schema; expiryEpoch is not mentioned at all. 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 (grant access) plus specific resource (a single memory cell named by cellId), with the granting counterpart to sibling saihm_revoke_share implicit in the wording. The scope guarantee ('Only that one cell is exposed') further sharpens what the tool is and is not.

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

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

Usage is implied: you call it when you want to give one other agent access to one cell, and the recipient must already be pinned out-of-band. But no explicit when-to-use/when-not and no sibling is named as an alternative or complement, leaving routing 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 the safe read profile (readOnly, idempotent, non-destructive). The description adds genuinely non-obvious behavior: the identity is derived locally by the client, and no plaintext appears because the server holds none. That privacy/architecture context is real value beyond the structured fields, though it omits any session prerequisites.

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

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

Three tight sentences, front-loaded with the verb and the returned fields, followed by the privacy note and the use case. 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?

An output schema exists, so return values need not be explained, and the description covers scope, data handling, and usage. The only omission is whether a session must first be established (e.g. via saihm_join) before the status is meaningful.

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

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

The tool takes zero parameters, which is the baseline-4 case. The schema is empty and fully covered, so there is nothing further the description needs to specify.

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

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

States a precise verb+resource ('Show the current SAIHM session') and enumerates exactly what is returned: agent identity, tier, custody mode, shard and sharing counts, and bfsi score. It is unmistakably distinct from the write-oriented siblings (remember, forget, share, revoke_share).

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?

'Use it to check which identity is active and what is stored and shared' gives a clear triggering context, so the agent knows when to reach for it. It stops short of naming alternatives or when-not conditions, but for a status read that is a small gap.

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