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

Discloses side effects beyond annotations: file is never uploaded (hashed locally), hash is registered on a blockchain-checkpointed audit chain, and a JWS receipt is returned. This adds privacy and verification details that complement the openWorldHint=true and idempotentHint=false 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 well-structured sentences: purpose, mechanism, and use cases. Every sentence provides necessary information with no repetition or 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?

Covers the anchoring workflow, output (JWS receipt), and offline verification, which is substantial given no output schema. Lacks error conditions or receipt contents, but this is acceptable when a sibling tool (check_artifact) may handle verification.

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

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

With 0% schema coverage, the description explains most parameters: path (hashed locally, not uploaded), sha256 (precomputed), kind (defaults to document), and label (short reference, no PII). It fails to mention `subject` and does not explicitly state mutual exclusivity of path/sha256, leaving a partial 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 clear action: 'Prove an artifact existed exactly as-is at this moment' — a specific verb and resource. It also distinguishes itself from siblings like check_artifact (verification) and get_audit_proof (retrieval) by focusing on the anchoring/creation act.

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 lists use cases (contracts, invoices, prescriptions, etc.) and gives the path/sha256 alternative. However, it does not contrast with sibling tools or state when not to use it, so no exclusions are mentioned.

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, lowering the burden; the description adds value by detailing the signed proof composition (riskPayloadJws + signingKeyId), the verification path via @fidacy/verify against the engine JWKS, and the default engine URL. This provides meaningful behavioral context beyond the annotations without contradicting them.

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

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

The description is four sentences, front-loaded with the primary action, and every sentence earns its place: purpose, proof/verification mechanics, key parameter semantics, and usage positioning. It is dense without being bloated.

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 6 parameters, nested objects, and no output schema, the description covers the core behavior well: what is returned (signed verdict with riskPayloadJws + signingKeyId), where it runs (live engine), and its role among sibling tools. It is incomplete only on the four ancillary parameters, which prevents a perfect score.

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 property descriptions are 0% covered, so the description must compensate. It adds real meaning for the two central parameters: kind (enum values, acting as a discriminator) and mandate ("the action/mandate object for that kind"). However, four remaining parameters (a2a, mandateType, idempotencyKey, spendingMandate) receive no explanation, including nested objects, leaving a partial compensation 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-resource-scope statement: "Return a SIGNED Fidacy trust verdict from the live engine... for a proposed action," which clearly states what the tool does. It also distinguishes itself from siblings by explicitly labeling this as "the verdict (advisory) layer" that "moves no money," contrasting with the payment-firewall 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 final sentence gives explicit usage boundaries: this is the advisory/verdict layer, it moves no money, and it complements the payment-firewall tools (request_payment et al.). This effectively tells the agent when to use it (for signed advisory verdicts) and when not to (when money needs to move), while naming an alternative tool family.

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

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

The description adds meaningful behavioral context beyond the annotations: it discloses that file paths are hashed locally and never uploaded, that the check is scoped to 'this account', and it explains the tampering signal interpretation. These details go beyond the readOnlyHint, idempotentHint, and destructiveHint already provided by annotations.

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

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

The description is remarkably concise: two sentences that cover purpose, usage, and interpretation without redundancy. Every sentence contributes new information. It is front-loaded with the main purpose and does not waste words.

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

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

The tool has no output schema, so the description must convey return semantics. It implies a result about the checkpoint state and explicitly describes the mismatch/tampering signal, but it does not specify the exact return format or fields. Given the simplicity of the tool and the annotations covering safety, the description is nearly complete, though a bit more detail on the output could push it to 5.

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 provides only names and types for 'path' and 'sha256' with no descriptions (0% coverage). The description compensates fully by explaining that the two parameters are alternatives ('Give a file path ... or a sha256'), clarifying the hashing behavior for the path, and defining the sha256 format implicitly. This is essential semantic information not present 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 clearly states the tool checks whether an artifact was anchored by this account and reports the state of its Bitcoin checkpoint. It uses a specific verb ('Check') and resource ('artifact'), and the title 'was this hash anchored?' reinforces the purpose. It is easily distinguished from siblings like 'anchor_artifact' which performs the anchoring.

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

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

The description explains how to use the tool: provide either a file path (hashed locally, never uploaded) or a sha256. It also provides interpretive guidance for the tampering signal when a hash does not match an expected anchored record. While it does not explicitly name alternative tools, the usage context is clear and practical.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable context about the output, including the tamper-evident proof and the explanation components, which goes beyond the annotations. There is no contradiction.

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

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

The description is concise and front-loaded, stating the core action in the first phrase. It uses only two sentences, with no unnecessary words, and every part adds value.

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

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

For a simple tool with one parameter and no output schema, the description adequately explains the tool's output content (request, mandate action, rationale, proof) and usage context. It does not cover edge cases or error behavior, but for this simplicity level, it is largely complete.

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

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

The schema has 100% coverage for the single parameter decisionId, with a clear description of its origin. The tool description does not add further meaning to the parameter, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Explain one decision in plain language' and enumerates the specifics (request, mandate action, rationale, proof). This distinguishes it from sibling tools like list_decisions (which lists decisions) and verify_mandate (which verifies mandates), making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use the tool: 'Use when an operator asks why a specific payment was blocked.' This clearly indicates a typical scenario, but it does not explicitly mention when not to use it or contrast with alternative tools, which would make it a 5.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds meaningful context about the return value (tamper-evidence, hash chaining, chain integrity, public key), which is valuable beyond the annotations. No contradictions found.

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

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

The description is a single, dense sentence that conveys all essential information without wasted words. It is front-loaded with the verb and resource, making it easy 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?

For a simple, one-parameter read-only tool with rich annotations, the description is nearly complete. It states what is returned, including key elements (chain integrity, public key). It doesn't include explicit return formatting, but the absence of an output schema and the low complexity make this 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%, so the schema fully describes the single parameter (decisionId) as 'Decision id returned by request_payment'. The description repeats 'decision id' but adds no additional meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Return') and the specific resource ('tamper-evident, hash-chained proof for a decision id'), while also detailing what the proof includes (chain intactness and verifying public key). This distinguishes it from sibling tools like request_payment or verify_mandate.

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

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

The description implies a use case (obtaining proof for a decision ID from request_payment) but provides no explicit guidance on when to choose this tool over alternatives like explain_decision or verify_mandate. The context is sufficient for simple use but lacks when-not-to-use or alternative comparisons.

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

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

The description adds significant behavioral context beyond annotations: it reveals the response includes payee, amount, reason, and blocking rule, specifies newest-first ordering, and notes it works offline. This complements the readOnlyHint and idempotentHint annotations without contradiction.

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

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

The description is compact yet information-dense: three short sentences covering purpose, return fields, ordering, filtering use case, and operational traits. No fluff or redundant details, and the main verb+resource appear immediately.

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

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

The tool has only two parameters, no output schema, and strong annotations. The description covers the return format (payee, amount, reason, rule), ordering, filtering, and safety traits, making it fully self-contained for an agent to invoke 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% (both parameters are described in the schema), so baseline is 3. The description reinforces the status filter's purpose by linking it to a concrete query ("what got blocked"), adding practical value beyond 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?

The description clearly states the tool lists recent agent payment decisions, specifies the ordering (newest first), the exact fields returned (payee, amount, reason, blocking rule), and distinguishes it from other tools by focusing on list/query behavior versus explanation or spending summaries.

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

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

It provides a clear use case ("Filter by status to answer 'what got blocked' directly"), which implies when to use the filter. However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of a 5.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true, etc.), the description adds the critical consent-based nature and the effect of attaching history to a real Fidacy account. It also preemptively clarifies side effects by stating it does not create an account or move money, which is valuable 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 two sentences, front-loaded with purpose, then a clear consent condition, and final exclusions. Every sentence earns its place with no redundancy.

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

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

For a simple one-parameter, opt-in tool with an output schema and annotations, the description covers purpose, usage conditions, and non-goals. It is fully self-contained and sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 100% for the single parameter, and the schema already explains 'The operator's email, exactly as they gave it.' The description adds no new technical format or constraints beyond reaffirming it is the operator's email, so baseline 3 is appropriate.

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

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

The description clearly states the specific action: 'Register the operator's email' and explains its purpose (so protection history attaches to a Fidacy account and Fidacy can reach them). It also explicitly distinguishes itself from creating an account or moving money, which differentiates it from siblings.

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

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

Provides explicit when-to-use guidance: 'ONLY call this when the human operator has explicitly given their email and agreed to be contacted.' It also clarifies what it does not do (does not create an account or move money), helping the agent avoid misuse.

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

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

With annotations providing safety hints (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds behavioral context: returns a signed grant or violated rule, and requires downstream verification. This goes beyond annotations by explaining the ALLOW/DENY outcome and the mandatory grant check. It does not contradict 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, front-loaded with the core action, then return behavior, then usage directive. No filler; each sentence adds distinct information.

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

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

The description covers the essential behavioral contract (authorize, return ALLOW/DENY, require grant, use before payment) for a 7-parameter tool with an output schema and annotations. It doesn't cover failure modes beyond the DENY rule, but output schema likely covers return specifics, so completeness is good.

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?

All 7 parameters have 100% schema description coverage, so the schema already documents each parameter. The tool description itself does not add parameter-level meaning beyond the schema, so a baseline 3 is appropriate.

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

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

The description uses a specific verb ('authorize') and resource ('payment action against the active Fidacy mandate'), and clarifies it returns ALLOW/DENY. It distinguishes from sibling tools like verify_mandate or assess_action by focusing on payment authorization.

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

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

The description explicitly states when to call it ('before any payment; never pay without it') and imposes a downstream requirement (MUST require the grant). It does not discuss exclusions or alternative tools when not applicable, but the context is clear.

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 read-only, idempotent, and non-destructive hints. The description adds value by stating the tool is deterministic, explainable, model-free, and based on the local audit chain, plus mentions the benchmark behavior. This goes beyond the structured annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and then provides a concrete use case. The enumeration of alert types is informative without being verbose. Every sentence earns its place.

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

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

For a simple read-only tool with one parameter and no output schema, the description is complete: it explains what it does, the specific pattern types, its deterministic and explainable nature, and when to use it. Annotations cover safety, and the schema covers parameters, so no gaps remain.

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 describes the only parameter 'limit' with full coverage (default 20, maximum 100, exclusive minimum 0). The description does not add additional parameter semantics, so the baseline of 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?

The description clearly states the tool provides predictive pattern alerts from the local audit chain, enumerating specific alert types (first-ever payee, amount spikes, velocity bursts, etc.). It distinguishes itself from siblings by focusing on unusual-pattern detection and is clearly separate from summary, proof, or decision 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 a clear use case: 'Use to answer has anything unusual happened before it becomes a loss.' It establishes context but does not explicitly name alternatives or state when not to use it. The title hint 'allowed, but outside this agent's pattern' provides some exclusions but remains implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds valuable context: it works offline against the local audit chain and clarifies that blocking occurs before execution. This goes beyond the annotation hints and enriches the behavioral understanding without contradiction.

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

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

The description is concise and front-loaded: it states what the report contains, then adds read-only/offline context, and concludes with example questions. Every sentence contributes meaning, with no fluff or redundant phrasing.

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 simple 1-param tool with no output schema, the description fully conveys what the report includes (payment decisions, paid amounts, recipients, blocked amounts, and mandate rules). It also provides example usage and notes offline capability. This is complete context for an AI agent to understand and correctly invoke the tool.

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

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

The only parameter 'days' is fully described in the schema (window in days, default 7, max 365), and the description's mention of 'time window' aligns but adds no additional technical detail. With 100% schema coverage, a baseline score of 3 is appropriate; the description doesn't need to compensate.

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

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

The description clearly states the tool's function: an operator report over a time window with specific metrics (number of payment decisions, amounts paid, recipients, blocked amounts, and mandate rules). This specific verb+resource+scope distinguishes it from siblings like list_decisions, which would provide detailed decisions rather than an aggregate summary. The example questions further reinforce its purpose.

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

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

The description provides clear context for when to use the tool ('Use this to answer questions like...'), with concrete example queries. However, it does not explicitly mention when not to use it or name alternative sibling tools, so it stops short of full when/when-not/alternatives 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 (readOnlyHint, idempotentHint, non-destructive) already provide a safety profile. The description adds valuable behavioral context: it 'Returns a link to open' and notes 'your anonymous usage is preserved and migrated to the new account'. This goes beyond the structured annotations to explain the outcome and state preservation, with no contradiction.

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

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

The description is two sentences long, front-loaded with the core purpose, and every clause adds meaningful information (upgrade target, benefits, return link, migration behavior). No wasted words.

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

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

Given the simplicity (0 params, no output schema) and rich annotations, the description is fully complete. It explains what the tool does, what it returns, and the migration behavior, so an agent can invoke it correctly without further missing 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, so there is nothing to explain. Per the baseline rule for 0-parameter tools, a score of 4 is appropriate—the description appropriately avoids any irrelevant param details.

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

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

The description clearly states the tool 'Start upgrading this local install to a real Fidacy account', specifying the verb and resource. It differentiates from siblings by mentioning the unique purpose of migrating a local install to a server-backed account, which none of the sibling tools address.

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

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

The description provides clear context for when to use the tool ('Start upgrading this local install to a real Fidacy account') and explains what the tool does. It does not explicitly mention exclusions or alternatives, but given the distinct nature of the tool among siblings, the usage context is sufficient.

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, covering safety. The description adds content detail (caps, allowed payees, window, revocation, public key), which is useful. However, it does not disclose behavior when no active mandate exists or any edge cases, so the added behavioral context is moderate.

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

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

The description is a single, concise sentence that front-loads the main action and resource, then lists the returned components. Every word contributes meaning, with no redundancy or filler.

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

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

Given there is no output schema and no parameters, the description carries the responsibility of explaining return values. It enumerates the envelope contents and the public key, giving a solid overview. However, it omits details about formatting, revocation semantics, or the absence of an active mandate, leaving minor gaps.

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

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

The tool has zero parameters, so the schema provides complete coverage. The description does not need to add parameter semantics, and the baseline of 4 is appropriate.

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

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

The description clearly identifies the tool as returning the active mandate envelope and Fidacy's Ed25519 public key for grant verification. It uses the specific verb 'Return' and details the resource contents, distinguishing it from sibling tools like spend_summary or get_audit_proof.

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

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

The description provides clear context by stating the purpose is 'for grant verification', which implicitly indicates when to use it. It does not explicitly mention alternatives or exclusions, but for a no-parameter read-only tool, the intended usage is evident.

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