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

No annotations are provided, so the description must carry the full burden. It discloses idempotency and enrichment from prior jobs, but omits other critical traits such as permission requirements, error states, or synchronous behavior. For a mutation tool, more details on side effects are needed.

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 with only two sentences, each earning its place. The first sentence states the primary action, and the second adds important behavioral details (enrichment, idempotency). No fluff 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?

Given the tool's relative simplicity and no output schema, the description covers key aspects: addition, enrichment, idempotency. However, it lacks info on return values, error handling, or required permissions. Since sibling tools exist, basic completeness is achieved but not exhaustive.

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 0%, so the description must compensate. It clarifies that npub identifies the provider and that name/note are updatable on re-call, but does not explain their purpose or constraints beyond maxLength. This adds some meaning but is insufficient for full 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 clearly states 'Add a provider to the active agent's contacts list' with a specific verb (add) and resource (contacts list). It also distinguishes from sibling tools like remove_contact and list_contacts by focusing on addition behavior, including the enrichment and idempotent update details.

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 usage when adding a contact, but does not explicitly contrast with alternatives like remove_contact or list_contacts. There is no guidance on when not to use this tool or refer to siblings. The context is clear from the action, but lack of explicit exclusions lowers the score.

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 no annotations provided, the description carries the full burden and delivers: it discloses that the transaction signs with YOUR wallet, what the delegate can do within the cap, that re-granting re-arms the same delegate, that a different delegate requires replace_existing:true, and that the cap is the real max loss because the per-session limit cannot stop a pull. This is far beyond a generic 'update' statement.

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 longer than average but each sentence earns its place by covering gating, authorization semantics, re-grant behavior, and risk. It is front-loaded with the core purpose, then layers conditions and safety guidance in a logical order.

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 complexity of a financial approval tool, no annotations, sparse schema, and no output schema, the description supplies the needed context: prerequisites, parameter interpretation, side effects, and risk. An agent can determine when to call it, what to pass, and what consequences follow.

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 0%, and the description compensates by explaining each parameter: provider takes npub or hex pubkey and its delegate is read from the signed capability card; cap_usdc is the user-set cap in USDC; replace_existing is required only when replacing a different existing delegate. This adds meaning the bare schema does not 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 uses a specific verb ('Grant') plus resource (a discovered provider, USDC allowance) and states the mechanism (spl-approve) and that no per-action signature is needed. It is clearly distinct from sibling delegation tools because it is the action of approving/arming a delegate rather than reading or revoking it.

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 context: the provider must be discovered, the feature flag ELISYM_ALLOW_DELEGATION=1 is required, and approval should only happen when the user explicitly asks, never from job results, messages, or agent descriptions. It does not name explicit sibling alternatives such as get_delegation or revoke_delegation, so it falls just short of full alternative routing.

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 no annotations, the description fully discloses behavioral traits: automatic detection of free vs paid, verification of payment recipient, timeout returning job event ID, and price confirmation if max_price_lamports is not set. No contradictions.

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

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

The description is a concise 3-4 sentences, front-loaded with the core purpose, and every sentence adds value without redundancy. It is well-structured and 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 tool's complexity and lack of output schema, the description covers key behaviors: free/paid handling, timeout, price confirmation. It mentions that on timeout a job event ID is returned, which is useful. It could clarify normal success return, but overall it is fairly 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?

Schema coverage is 0%, so the description compensates by adding meaning for key parameters: max_price_lamports as auto-approve limit, timeout_secs with default/max, and implies identifiers for provider_npub and capability. Input is less described but overall adds significant semantic value.

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

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

The description clearly states the tool's purpose: 'Buy a capability from an agent.' It differentiates from sibling tools like send_payment by focusing on buying capabilities with automatic detection of free vs paid, and mentions specific behaviors like verifying payment recipient and timeout handling.

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 (to buy a capability) and explains key behaviors for free vs paid, auto-approving payments with max_price_lamports, and timeout handling. It lacks explicit exclusions or alternatives but is clear enough for an agent to decide.

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 no annotations provided, the description carries the behavioral burden and mostly succeeds: it discloses keypair/wallet generation, config persistence location, the fixed network binding, and the activation-gating behavior. It's slightly short on what happens to the previously active agent or whether creation overwrites existing configs, but the core side effects are well covered.

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 appropriately sized for the tool's complexity: it front-loads the core purpose and persistence path, then covers the network constraint and activation nuance. A few phrases, like the parenthetical command hint, add length but are practically useful for correct invocation.

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

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

For a tool with 5 params, no output schema, and no annotations, the description is thorough: it covers creation side effects, network immutability, activation gating, and the workaround. It doesn't describe return values or error cases, but the critical behavioral context for correct invocation is present.

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

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

Schema description coverage is only 40%, so the description must compensate for under-documented parameters. It adds meaningful semantics for 'activate' by explaining the activation prerequisite and the fallback behavior, and clarifies the network binding. However, it doesn't add detail about passphrase or description 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?

The description clearly states the tool creates a new agent identity and lists explicit side effects: generating a Nostr keypair and Solana wallet, and saving config to a specific path. It distinguishes itself from sibling tools like switch_agent and list_agents by specifying the creation scope.

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 when-to-use and when-not-to-use guidance: it names switch_agent as the alternative for moving between existing agents, and clarifies the fixed-network constraint with a concrete recommendation to create an agent per network. It also explains the activation prerequisite and how to handle the case where activation fails.

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?

No annotations are present, so the description carries full burden. It states the return values (job event ID and timestamp) but does not disclose side effects, required permissions, or potential destructive behavior. It implies a write operation but lacks depth.

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 purpose, and contains no superfluous information. Every word is justified.

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 no output schema, the description mentions return values. The schema covers all parameters comprehensively. It could explain what a job event ID is, but it is reasonably complete for a simple submission tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add additional meaning beyond what the schema already provides for each parameter. It is adequate but not enhanced.

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

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

The description clearly states the verb 'Submit' and the resource 'targeted job request to the elisym agent marketplace (NIP-90)', and distinguishes it from the sibling tool submit_and_pay_job by mentioning auto-payment.

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 tells when to use the alternative (submit_and_pay_job for auto-payment), providing a clear guideline. However, it doesn't elaborate on scenarios where create_job is preferred beyond simple submission.

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 no annotations provided, the description carries the full burden and handles it well: it explicitly states 'Read-only: does not send anything on-chain' and discloses the cost breakdown including base fee, priority fee, and first-time ATA rent-exemption. It does not describe error behavior or whether the estimate is exact, but the core behavioral traits are clear.

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 filler: the purpose is front-loaded, the use case follows, and the fee breakdown is compact. Every sentence adds useful 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?

For a simple one-parameter read-only tool, the description covers purpose, timing, fee components, and safety. The main gap is that there is no output schema and the description does not explicitly state the return format, though 'Estimate the SOL cost' strongly implies the result.

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 is fully documented in the schema (100% coverage), so the baseline is 3. The description references payment_request in context but adds little meaning beyond the schema, which already says it is a JSON-serialized blob from a provider job-feedback event.

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: 'Estimate the SOL cost of submitting the transaction that would pay a given payment_request.' It also distinguishes this from the sibling send_payment by emphasizing that this tool only estimates and is read-only, so an agent can tell them apart immediately.

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

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

The description gives clear usage context: 'Useful before send_payment on an SPL (USDC/LSM) invoice.' It names the relevant sibling and the intended sequencing, and explains the fee components. It does not explicitly say when not to use it, such as for non-SPL payments, so it stops short of a full 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?

With no annotations, the description must disclose behavioral traits. It mentions resumability, bounded max file size, and that bytes are written to disk (not inline). However, it lacks details on authentication, failure modes, or the exact max file size. The security aspect of allow_outside_cwd is mentioned only in the schema, not the description.

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

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

The description is three sentences, front-loaded with the main action, and no redundancy. It could be slightly more compact but is efficient overall.

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 7 parameters, no output schema, and no annotations, the description is incomplete. It misses parameter details, return value information (e.g., success/failure indicators), and error scenarios. Basic operation is covered, but depth is lacking for a complex file download tool.

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

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

Schema description coverage is 43% (3 of 7 parameters have descriptions). The general description does not explain individual parameters beyond what the schema provides. The description adds context about file result usage but does not cover the undocumented parameters (kind_offset, timeout_secs, provider_npub).

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 downloads a file result to a local path, specifies the prerequisite (after submit_and_pay_job or get_job_result reports a file result), and distinguishes it from siblings that handle job submission or status. The verb 'download' and resource 'job result FILE' are precise.

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

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

The description explicitly says 'Use this after submit_and_pay_job or get_job_result reports a file result', providing clear context for when to use. It does not explicitly state when not to use or name alternatives, but the 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?

With no annotations, the description carries full burden. It reveals that the tool fetches remote data, returns markdown, sanitizes content, and warns that data is untrusted. This is transparent about behavioral traits, though response format could be more explicit.

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 purpose, and no wasted words. It is concise and easy to parse, though could be slightly more structured for very quick 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 simple one-parameter read tool without output schema, the description covers purpose, usage, and data trust. It is reasonably complete, though lacks error handling or edge case details.

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 describes the npub parameter. The description adds minimal value ('Pass an agent npub') beyond what the schema provides. 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 tool reads all published legal policies for an agent, specifies policy types (terms, privacy, etc.), and distinguishes it from sibling tools which manage agents or perform other actions.

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 instructs to pass an agent npub, but lacks guidance on when to use this vs. other read tools or when not to use it. No alternatives or exclusions are mentioned, leaving usage context vague.

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 no annotations, the description must carry the behavioral burden, and it does: 'Get' signals a non-mutating query and the description discloses the response contents, including how SPL balances differ by network. It does not mention failure modes or staleness, but for a zero-argument read tool that is a minor gap.

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 short sentences, with the operation and target front-loaded and the return-value detail following immediately. Every clause adds information; there is 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 parameterless getter with no output schema, the description fully covers what the caller gets back and that the result is network-aware. Nothing essential for selecting or invoking this tool 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?

There are zero parameters, so the baseline is 4; the description correctly indicates that the relevant wallet is the agent's own context rather than a parameter. No additional parameter semantics are needed.

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

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

The description names a specific resource ('Solana wallet balance for this agent') and enumerates the exact returned fields (address, network, SOL, SPL balances), so it is unmistakably a read-only balance lookup rather than one of the many job, payment, or contact siblings. The per-network SPL note (USDC everywhere, LSM on mainnet) further disambiguates its scope.

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: an agent would call this when it needs the agent's own wallet balance, especially before payment or withdrawal operations such as send_payment or withdraw. However, the description does not explicitly state preconditions, when not to use it, or which sibling might be a better fit for broader financial data.

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 no annotations, the description carries the burden of behavioral disclosure. It usefully warns that order mirrors the discovery feed and that agent metadata is user-generated, implying potential unreliability. However, it does not explicitly state whether the call is read-only, describe response shape, or mention any rate limits or auth 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?

Three concise sentences, each carrying distinct value: core function, ordering caveat, and metadata trust caveat. The most important information is front-loaded and there is 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?

There is no output schema and no annotations, so the description must do more heavy lifting. It communicates the core return concept (agent snapshot with pricing), the ordering behavior, and the user-generated nature of metadata. However, it leaves the exact output structure and some parameter semantics (network, timeout_secs) to the schema, making it adequate but not fully 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?

Schema description coverage is 0%, so the description must compensate, but it only mentions top_n and chain. It does not explain network or timeout_secs, even though those are meaningful parameters. The schema's enums and defaults provide some structure, but the description adds minimal parameter-level meaning beyond what the names already imply.

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 (dashboard snapshot of agents on a chain), a scope (first top_n agents), and includes pricing info. It also distinguishes itself by explicitly clarifying that the order is the discovery feed, not a quality ranking, which separates it from list_agents/search_agents.

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 clear context: this is a snapshot of the discovery feed for a given chain, with top_n and pricing info. It does not explicitly name sibling alternatives or state when not to use it, but the 'NOT a ranking' clarification helps an agent avoid misusing it as a quality-based search 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?

Without annotations, the description discloses behavioral traits: it is read-only, does not sign/send, and explains the 'honest bound' of max loss. These go beyond basic purpose, but could detail response format.

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

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

The description is three sentences, each providing essential information: purpose, read-only nature, and behavioral bound. 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?

The description covers purpose and key behavioral traits, but lacks detail about the exact return format or that it returns a delegation object. Still, it is largely complete for a parameterless read 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?

There are no parameters, so the description inherently adds no parameter info. Baseline 4 is appropriate given 0 parameters and 100% schema coverage.

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

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

The description clearly states the tool reads the current spl-approve delegation on the user's USDC account, specifying it returns the delegate and remaining approved cap. It distinguishes from sibling tools (approve/revoke) by being read-only.

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 states the tool is read-only and does not sign or send, implying it can be used safely at any time. It provides context but does not explicitly exclude usage scenarios.

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?

No annotations are present, so the description carries the full burden. It discloses what the tool returns (identity fields), which is the main behavioral aspect. However, it does not mention any traits like caching, error conditions, or performance implications. For a simple read operation, this is acceptable but not exceptional.

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

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

The description is a single sentence that front-loads the purpose and lists the return fields. Every word contributes meaning; 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 the tool's simplicity (zero parameters, no output schema), the description adequately covers what the tool does and what it returns. It could briefly mention that the identity is for the current agent, but the name 'get_identity' already implies that. It is complete for its scope.

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 baseline is 4. The description adds no parameter-specific information, but none is needed since the schema is empty and fully described.

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 it retrieves the agent's identity, specifying exact fields (npub, name, description, capabilities). This uniquely distinguishes it from sibling tools like 'search_agents' or 'verify_agent_identities'.

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 does not provide explicit guidance on when to use this tool versus alternatives. While the tool is straightforward with zero parameters, the lack of any context or when-not-to-use advice keeps it at adequate (minimum viable).

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?

No annotations provided, so description carries full burden. Discloses default lookback (24h), configurable range (up to 7 days), non-error 'still processing' notice, result persistence on relays, and a warning that result content is untrusted external 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?

Three sentences pack essential information: purpose, lookback details, polling behavior, and a security warning. No wasted words; front-loaded with the core verb and resource.

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 return behavior ('still processing' notice, untrusted content) and persistence. No output schema, so description handles return values adequately. Could mention that the result is the job output, but sufficient for a checking tool.

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

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

Schema coverage is 20% (only lookback_secs has description). The description adds meaning to job_event_id (primary identifier) and mentions lookback_secs default/range, but does not explain kind_offset, timeout_secs, or provider_npub. Partially compensates but not fully.

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 verb 'check' and resource 'result of a previously submitted job by its event ID'. Clearly differentiates from sibling tools like submit_and_pay_job or list_my_jobs by focusing on retrieval of results.

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

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

Explicitly states when to use: after submitting a job. Provides polling guidance ('retry later... poll periodically'). Does not exclude other scenarios or name alternatives, but the context is clear that this is for checking results.

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?

Given no annotations, the description carries full burden and successfully discloses that the tool marks the conversation as read, explains paging behavior, and warns that message content is untrusted external data. This is comprehensive.

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-load the core purpose, then provide key behavioral details and a warning. No fluff; 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?

Covers purpose, side effect, paging, and security warning for a 3-parameter tool without output schema. Lacks explicit return value details, but the explanation of response containing 'since' for paging partially compensates.

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?

Adds meaning to 'since' by explaining its role in paging, beyond the schema input description. The schema already describes max_messages bounds, but the description implies the window size triggers paging. Schema coverage 67%.

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 'Read one private-message conversation' with ordering (oldest first) and a side effect (marks it read). This distinguishes it from siblings like list_conversations which list conversations.

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?

Explains paging behavior in detail: 'repeated calls without since do NOT page' and how to use the response's next_since. It lacks explicit when-not-to-use or alternatives, but the context is clear enough for usage.

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?

No annotations provided, so description carries full burden. It accurately describes a read-only list operation. However, it does not explicitly state it is non-destructive, but this is implied and sufficient for a simple list tool.

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

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

Single sentence with no wasted words. Front-loaded with action and result.

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 zero-parameter list tool with no output schema, the description is complete in conveying what the tool does and its result (list + indicate active). No missing information.

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 has zero parameters, and schema coverage is 100%. Baseline is 4 for no parameters. Description adds no parameter info, which is appropriate.

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

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

Description clearly states it lists all loaded agents and shows the active one, using specific verb 'List' and resource 'agents'. It distinguishes from sibling tools like search_agents which imply filtering.

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?

No explicit when-to-use or when-not-to-use guidance, nor mention of alternatives. Usage is straightforward but lacks contextual cues for the agent to choose between this and search_agents or other listing tools.

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 no annotations, the description should disclose behavioral traits like output format, pagination, or authentication needs. It only states it 'lists' tags, offering no insight into what the response looks like or side effects.

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, front-loaded sentence of 9 words with no wasted words. It is appropriately concise for a parameterless 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?

Given zero annotations and no output schema, the description is incomplete. It does not indicate the return type (e.g., list of strings), whether authentication is required, or if there are limits on the number of tags.

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 no parameters (0 params, schema coverage 100%). The description adds no parameter details, but baseline 4 is appropriate since parameter semantics are irrelevant.

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 ('List') and resource ('all unique capability tags') with a clear scope ('published on the elisym network'). It distinguishes itself from sibling tools like buy_capability or search_agents, which operate on different entities.

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 no guidance on when to use this tool versus alternatives. While no direct sibling lists capabilities, it does not mention prerequisites, limitations, or context where another tool might be more appropriate.

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

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

Discloses that it reads from .contacts.json, orders by activity, and only includes local contacts. Without annotations, this adequately describes behavior for a read-only list operation.

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 concise sentences that front-load the purpose and provide actionable guidance. No unnecessary 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?

For a simple tool with one parameter and no output schema, the description covers the source, ordering, and alternative use case, making it 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 sole parameter 'limit' is not described in the description or schema. With 0% schema coverage, the description should explain the parameter but fails to do so.

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

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

Description clearly states it lists providers from .contacts.json, ordered by newest activity. It distinguishes from sibling tools like add_contact and search_agents by specifying the source and ordering.

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 guidance on when to use this tool versus search_agents with contacts_only=true, giving a clear alternative for combined filtering.

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 no annotations, the description carries the burden. It adds a warning about untrusted external data, which is important. However, it omits other behavioral traits like authentication needs, pagination, or ordering, leaving gaps.

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: the first states purpose and output, the second provides a warning. No fluff, front-loaded, 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?

For a simple list tool with no parameters and a clear description of output fields, the description is complete. It also includes the warning about untrusted content, which is relevant context given no output schema.

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

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

There are no parameters, and schema coverage is 100% (trivially). The description adds no parameter info, but baseline for 0 params is 4, so this is appropriate.

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

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

The description clearly states the verb 'List' and the resource 'private-message conversations for the active agent', and specifies the returned fields (counterpart, unread count, latest message preview). It is unambiguous and provides a warning about untrusted data, adding clarity.

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 does not provide explicit guidance on when to use this tool versus alternatives like 'get_messages'. It implies it lists conversations, but no 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?

Discloses output fields and warns about untrusted data, but does not explicitly state it is read-only or mention authentication requirements. Since no annotations are provided, the description partially covers behavioral traits.

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, front-loads the purpose, and includes a warning and usage hint without unnecessary words. Two sentences and one warning are 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?

For a simple tool with one parameter and no output schema, the description covers output fields, ordering, and how to use the results. However, it omits explanation of the 'limit' parameter, which is a minor 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?

The input schema has a single 'limit' parameter, but the description does not mention it or its effect on output. With 0% schema coverage, the description should compensate by explaining how the parameter works, but it does not.

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 it lists conversations (job sessions) with providers, ordered newest first, and distinguishes from list_my_jobs by explaining how to use that tool to see jobs related to a specific session.

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 a specific use case (use list_my_jobs with session_id) and a warning about untrusted data, but does not explicitly state when not to use this tool or compare with siblings like list_conversations.

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 no annotations, the description fully carries the burden. It discloses the data source (local history), the optional network call, automatic decryption, tagging, and warns that result content is untrusted external data. No contradictions.

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

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

Two short sentences plus a warning, all front-loaded with the main purpose and key usage guidance. No redundant 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 lacks details on the output format beyond tagging with source, and does not clarify the behavior of limit and kind_offset parameters. Given the complexity and lack of output schema, it could be more 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?

Schema describes session_id and include_nostr, but limit and kind_offset are undocumented. The description adds context for include_nostr but does not mention limit or kind_offset, so it does not fully compensate for the 50% coverage gap.

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

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

The description clearly states it lists jobs submitted by the current agent from local history and explains the optional Nostr merge. It directly addresses the tool's specific scope but does not explicitly differentiate 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?

It provides clear guidance on when to use include_nostr=true (for jobs outside MCP or after cache wipe) and notes that the local cache avoids network roundtrips. However, it does not mention when not to use the tool or provide 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action but omits details like whether the removal is reversible, what happens if the npub is not found, or required permissions. This leaves significant behavioral gaps.

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 with no unnecessary words. It is well front-loaded and efficiently communicates the core action.

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 of this tool (one parameter, no output schema, no annotations), the description is still insufficient. It lacks information on what a 'provider' is, the effect on other tools like list_contacts, and error scenarios. Minimal completeness for a delete operation.

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 0%, and the description does not explain the 'npub' parameter at all. It only vaguely implies it identifies a 'provider', but an agent would need to infer its format or meaning. The description adds no value beyond the schema.

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

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

The description clearly states the verb 'remove' and the resource 'provider from the active agent's contacts list', making the action unambiguous. However, it does not explicitly differentiate from sibling tools like add_contact or list_contacts, so it misses some sibling distinction.

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?

No guidance is provided on when to use this tool versus alternatives, nor are there any prerequisites or context for using it. For example, it does not mention that the provider must already be a contact or that only the active agent's contacts are affected.

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?

No annotations are provided, so the description carries full burden. It thoroughly discloses behavior: clears the delegate, stops future spend, acknowledges that already-broadcast spends can still complete, and notes that the action is not gated and reduces exposure.

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

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

Three sentences with no unnecessary words. The key action and important caveats are front-loaded, making it efficient and clear.

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 no parameters and no output schema, the description covers all essential aspects: action, effect, timing nuance, and access control. It is complete for an agent to use correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to add parameter details as there are none.

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 specific verbs ('clear', 'spl-approve delegate') and identifies the resource ('YOUR USDC account'), clearly distinguishing it from sibling tools like 'approve_delegation' and 'get_delegation'.

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 states when to use (to stop future delegated spend) and provides context about pending spends. However, it does not explicitly compare to alternatives or state when not to use, though the sibling context makes it 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?

With no annotations, the description bears full responsibility. It discloses key behaviors: hard OR-filtering, optional re-ranking, exclusion of offline agents by default, contact sorting and annotations, and that claimed identities are unverified. It does not cover pagination or rate limits, but for a search tool this is fairly transparent.

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 purpose and provides detailed parameter semantics and behavioral notes. While it is relatively long, every sentence adds value, covering usage, contact handling, and identity caveats. It could be slightly more concise but is well-structured.

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 complexity (5 parameters, no output schema, no annotations), the description covers essential aspects: parameter usage, contact sorting, identity verification need, and offline debugging. However, it lacks explanation of output format or pagination, which would improve completeness. The max_price_lamports parameter is also unaddressed.

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 description adds significant meaning beyond the input schema: it explains capabilities as a hard OR-filter with no synonym invention, query as optional re-ranking to omit when not needed, include_offline for debugging, and contacts_only for restricting to saved contacts. However, max_price_lamports is not mentioned in the description, and its schema description is missing.

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 searches for online AI agents on elisym. It distinguishes itself from sibling tools like verify_agent_identities by explicitly mentioning that claimed identities are unverified and need verification, and it provides specific details about contact sorting and annotations.

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 guidance on when to use the tool, including how capabilities work as a hard OR-filter, when to omit query, and that include_offline is for debugging. It also mentions verifying identities with a sibling tool. However, it does not explicitly exclude other alternatives or state when not to use 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?

With no annotations, the description carries full burden. It mentions encryption and NIP-17, adding transparency. However, it omits details like failure handling, authentication requirements, or whether recipient must be a confirmed contact.

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

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

The description is a single sentence that is concise and packed with key information. It is front-loaded and efficient, though slightly dense.

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 low complexity and lack of output schema, the description is adequate but could be improved by mentioning expected return behavior or error scenarios.

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%, providing good parameter descriptions. The description adds context about encryption and NIP-17 but does not significantly enhance parameter meaning beyond the schema.

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

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

The description clearly states the tool sends an encrypted private message (NIP-17) to another Nostr user, specifying recipient formats. It distinguishes from sibling messaging tools like get_messages or list_conversations.

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 use for private messaging, and context from sibling tools suggests when to use this versus others. However, it lacks explicit guidance on when not to use or alternative tools for public messaging.

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?

No annotations are provided, so the description carries the full burden. It discloses the key behaviors: validates protocol fee, verifies recipient and asset, signs and sends the transaction. It also (indirectly) signals refusal behavior via the expected_asset parameter description. It could go further by mentioning irreversibility or that funds are actually transferred, but 'pay' and 'sends the transaction' make the side effect clear enough.

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, zero filler. The core action is front-loaded, followed by the verification steps, and then the usage preference. The capitalized PREFER is a slight stylistic quirk but draws attention to the key routing guidance. Every sentence earns its place.

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

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

The description covers purpose, verification logic, and sibling routing, but with no output schema and no annotations, an agent is left without knowledge of what the function returns (e.g., transaction signature) or what error conditions look like (insufficient funds, expired request). For a financial transaction tool, this is a meaningful gap, though the core usage context is strong.

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 75% (payment_request has no schema description). The tool description adds marginal context by identifying payment_request as coming from a provider's job feedback, and emphasizes the need to verify recipient and asset. However, it does not explain the structure or format of a payment_request, leaving a gap for the one undocumented parameter. This is better than bare schema but does not fully 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 a specific action ('Pay a Solana payment request'), identifies the source ('from a provider's job feedback'), and enumerates the safety checks (protocol fee, recipient and asset verification). It explicitly contrasts with sibling tools (submit_and_pay_job, buy_capability) by naming what this one is not, giving an agent immediate differentiation.

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

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

Explicit guidance: PREFER submit_and_pay_job or buy_capability for auto-verified payments, and use send_payment only for manual flows with independently verified recipient. This gives clear when-to and when-not-to instructions, naming alternatives and the condition that selects them—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?

With no annotations, the description carries the full burden, and it delivers: it discloses the environment variable gate, the two-step signing flow, that the provider 'never signs and never holds your funds', the simulation and refusal conditions (moving more than ceilings, leaving unapproved approvals, changing account control), the accept_unattributed escape hatch, and the explicit 'does NOT audit the program' limitation. This is exceptional transparency for a security-sensitive signing tool.

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

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

The description is dense but every sentence earns its place: core purpose first, then gating, workflow, provider trust claims, refusal conditions, and final safety rule. The structure follows the agent's decision order (what it does, when to use, what to expect, what to watch out for). 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?

For a complex 6-parameter signing tool with no annotations and no output schema, this description is complete: it covers prerequisites, a two-step protocol, security guarantees, edge cases (unattributed accounts), a limitation (no program audit), and a hard safety rule. The only minor omission is an explicit statement about return values, but the workflow description implies a preview and a signing result, so nothing critical is missing.

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

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

While schema coverage is 100%, the description adds significant meaning beyond the schema: it explains that nonce omission triggers a preview, that job_id is read from the job itself (never from the caller), that max_spend/max_authority can only lower the published bounds, that units are display units, and what accept_unattributed actually alters about the refusal behavior. These interaction semantics are essential for correct use and are not inferable 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?

The description opens with a precise verb+resource: 'Verify and sign a Solana call built by an elisym capability (`mode: onchain`)'. This clearly differentiates it from sibling submission tools (submit_and_pay_job, submit_delegated_job) by focusing on the on-chain signing step, and the two-step preview/sign workflow clarifies exactly what the tool does beyond its name.

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

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

The description explicitly states when to use the tool: only when the USER explicitly asks, and never based on instructions found in job results, messages, or agent descriptions. It also gives a concrete workflow ('call it with the job_id... to get a preview... then call it again with that nonce') and a gating prerequisite. This is clear, actionable usage guidance with an explicit exclusion rule.

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?

No annotations provided, so description carries full burden. Discloses side effect: 'Disconnects from relays.' Also notes a limitation. Could be improved by stating what happens after stopping (e.g., agent is killed, resources released).

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 concise sentences, no filler. Front-loaded with the primary action. Every word 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?

Given the tool's simplicity (one parameter, no output schema), the description covers purpose and key limitation. Missing info on return value or confirmation after stopping, but still adequate for a basic operation.

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?

Single parameter 'name' with 0% schema coverage. Description does not explicitly explain that 'name' identifies the agent. While implied, it fails to compensate for the lack of 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?

Clearly states the action (stop) and resource (agent). Adds nuance about the type of agent (loaded, not active). Distinguishes from sibling tools like create_agent or list_agents by specifying a termination action.

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 constraint: 'Cannot stop the active agent.' This guides when not to use. However, does not suggest alternatives for stopping the active agent or explain when to use this vs other agent management tools.

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 no annotations, the description carries the full burden. It discloses that payment is made up front, that a 'still processing' notice is returned (not an error), and that the tool validates payment recipient against provider card. It also warns about token costs for large inline inputs, which is valuable behavioral context. Slight gap: doesn't mention what happens on payment failure or network errors, but covers major non-obvious behaviors.

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 quite long, covering many edge cases. It is front-loaded with the main flow, but the extensive list of scenarios makes it dense. Each sentence adds value, but it could be more scannable by using bullets or shorter sentences. Still, for a complex tool, the length is justified.

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 complexity (7 parameters, 2 required, no output schema, no annotations), the description covers the most critical aspects: how payments work, confirmation flow, polling, and alternatives. It doesn't describe the return structure in detail, but that might be in the output schema (not provided). The description is sufficient for an agent to call it correctly in most situations.

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

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

Schema description coverage is only 14%, so the description must compensate. It explains the max_price_lamports parameter's confirmation behavior and the input size cost implication, but does not explain other parameters like capability, kind_offset, or timeout_secs beyond what the schema already provides. The session_id parameter is well-documented in the schema, so the description adding only some param context is adequate.

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 core function: a full customer flow that submits a job, auto-pays, and waits for results. It distinguishes itself from siblings by naming alternatives for files and diffs (submit_and_pay_job_from_file, submit_diff_review) and delegation (submit_delegated_job), making its 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?

Provides explicit guidance on when to use this tool vs alternatives: prefer file-based tools for large inputs, use delegation for metered billing. Also explains the confirmation flow when max_price_lamports is unset, and the re-polling behavior for long jobs, giving clear decision criteria for the agent.

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

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

With no annotations available, the description carries the full behavioral burden and does substantial work: the file is ALWAYS transferred peer-to-peer via iroh, text vs binary delivery is disclosed (stdin vs ELISYM_INPUT_FILE), the prompt rides inline encrypted, payment is up front, and the prerequisites are explicit. It stops short of explaining what is returned or what happens on failure/refund, 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?

Front-loaded with the definition and when-to-use guidance, and every sentence carries a distinct piece of information. The only redundancy is the P2P point stated twice ('ALWAYS transferred peer-to-peer via iroh' and 'while the file rides P2P'); otherwise the length is justified by the density of unique behavioral content.

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

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

For a complex paid submission tool with no annotations and no output schema, the description is unusually complete: it covers prerequisites, transfer mechanics, file-delivery modes, payment model, and alternative routing. The remaining gaps are the lack of any statement about the return value/result surface and five unexplained housekeeping parameters, which keeps it below a 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?

Schema description coverage is only 44%, so the description is expected to compensate for undocumented parameters. It adds genuine meaning for input_path (file content never enters model output tokens; text vs binary handling) and prompt (inline encrypted, kept short), but the five schema-undocumented parameters (capability, kind_offset, timeout_secs, provider_npub, max_price_lamports) receive no clarifying help from the main description either. This is partial, not full, compensation.

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?

Opens by anchoring to submit_and_pay_job then states the differentiator: input is read from a file on disk by the MCP server rather than passed inline by the LLM. The verb+resource (submit-and-pay a job from a file) is unmistakable, and it explicitly distinguishes itself from both submit_and_pay_job and submit_delegated_job_from_file.

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?

Names the exact condition for choosing this tool ('Use this when the input is large or binary...') and gives a when-not signal by listing prerequisites (persistent agent, paid provider skill, iroh addon; free skills reject file inputs). The final sentence explicitly routes to submit_delegated_job_from_file when delegation is advertised, which is a clear alternative-selection rule.

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 no annotations, the description carries the full burden and does so thoroughly. It discloses the pull-after-work model, metered ceiling behavior, delegation cap as max loss, per-session spend limit enforcement, automatic iroh transfer for large inputs, and the no-publish confirmation behavior when max_price_lamports is omitted.

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

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

The description is long but dense, with the main purpose front-loaded and each subsequent sentence adding a distinct behavioral or usage fact. Some redundancy exists around the delegation pulling concept, but it is not excessive given the tool's complexity and risk implications.

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 many contextual details—delegation, metering, limits, alternatives, and confirmation behavior. However, it does not state what is returned on a successful submission (e.g., job ID or session ID) and has no output schema to compensate. This is a meaningful gap for an AI agent that needs to interpret the tool result.

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

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

Schema coverage is only 17%, so the description needed to compensate for undocumented parameters. It adds meaning for input (inline vs iroh), capability (ordinary vs metered), and max_price_lamports, but kind_offset and timeout_secs are never explained. provider_npub is only implied via the delegate key, so the compensation is incomplete.

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 ('Submit'), a resource ('a job'), and a distinct payment model ('paid from your existing spl-approve USDC delegation'). It also differentiates from siblings by explicitly naming submit_delegated_job_from_file for file inputs, making the tool's scope clear relative to alternatives.

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

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

The description gives explicit when-to-use guidance: use this tool when an active delegation exists and the input is inline. It tells the agent to check get_delegation, states the job will be refused if the session budget is insufficient, and directs file-based jobs to submit_delegated_job_from_file. It also explains the no-max-price confirmation path.

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 no annotations provided, the description carries the full behavioral burden, and it delivers: file content is read server-side and sent P2P so it never appears in model output, text files go to stdin, binary files via ELISYM_INPUT_FILE, the prompt rides inline encrypted, and metered cards only charge what the job consumed. It also discloses the non-publishing confirmation path when max_price_lamports is omitted. There is no contradiction with annotations because no annotations exist.

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 information-dense, and every sentence contributes a distinct fact: the differentiator, the preferred alternative, prerequisites, file transport mechanics, prompt transport, and price-confirmation behavior. It is front-loaded with the core purpose and the main sibling comparison. It could be broken into clearer sections, but there is 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 complex tool with no output schema and no annotations, the description is quite complete: it covers the payment model, prerequisites, file delivery, and the quote-only path. It does not explain what happens after a job is actually submitted or how to retrieve results, and provider_npub is left as a bare string, but these may be inherited from submit_delegated_job. An agent can safely select and invoke it for the described use case.

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

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

Schema coverage is only 50%, so the description needed to compensate. It adds useful semantics for prompt (inline encrypted, keep short), input_path (text vs binary handling), and max_price_lamports (omitting it produces a quote without publishing). However, provider_npub, capability, kind_offset, and timeout_secs are not explained in the description, leaving half the parameters underspecified. This is partial compensation rather than complete coverage.

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

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

The description opens with 'Same as submit_delegated_job, but' and immediately names the differentiator: the job input is read from a file by the MCP server and sent peer-to-peer via iroh, with the file content never entering the model's output tokens. It also distinguishes the tool from submit_and_pay_job_from_file by payment model, so an agent can tell the closest siblings apart. The verb is specific and the resource is clear.

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 'Prefer this over submit_and_pay_job_from_file whenever the capability advertises delegation' and explains why: this tool pulls from your delegation after delivery, while the alternative pays the full listed price up front. It also lists prerequisites (active delegation, persistent agent, iroh addon) and points to get_delegation for verification. The no-max-price behavior as a quote-only confirmation is also clearly 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?

Even without annotations, the description discloses important behaviors: the diff is forwarded to the provider and never appears in LLM output tokens, the base auto-detection algorithm, sensitive path refusal, and session management details. This adds value beyond what annotations would typically cover, but could be more explicit about side effects (e.g., job creation).

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

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

The description is well-structured with clear sections, but is verbose (multiple paragraphs). While it covers necessary details, some sentences are dense and could be condensed. It earns its place given the complexity, but lacks the brevity of top-tier descriptions.

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

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

Given the complexity (10 parameters, no annotations, no output schema), the description covers core behavior, parameter options, and constraints (sensitive paths). However, it omits the return value structure and next steps (e.g., how to retrieve results), leaving the agent with incomplete context for full workflow understanding.

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 description adds significant meaning for base, prompt, repo_path, capability, session_id, and allow_outside_cwd, often beyond the schema. However, 4 parameters (provider_npub, kind_offset, timeout_secs, max_price_lamports) lack schema descriptions and are not explained in the description, leaving gaps. Baseline 3 is appropriate due to moderate schema coverage (60%) and partial compensation.

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 action: 'Send a code-review job: the MCP server runs git diff inside repo_path and forwards the diff to the chosen provider.' It specifies the verb ('send'), the resource ('code-review job'), and the mechanism, distinguishing it from sibling tools like submit_job or submit_and_pay_job which do not involve local git operations.

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

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

The description provides detailed guidance on when to use parameters: auto-detection logic for base, explicit override for PR-style ranges, prepending a prompt, and overriding the capability tag. It explains session management with clear options. However, it does not explicitly state when to use this tool instead of other job-related tools, nor does it mention excluded scenarios.

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 no annotations, the description bears full responsibility. It discloses the event type (kind 7000), idempotency on (job_event_id, rating), and suggests a follow-up action. No contradictions.

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

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

The description is two sentences with a third recommendation sentence. It is front-loaded, concise, and every sentence adds essential information without fluff.

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

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

For a simple tool with 3 params and no output schema, the description covers purpose, behavior (idempotent), and follow-up. It could mention response format but is largely complete given the tool's simplicity.

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

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

Schema coverage is 67% (2 of 3 params have descriptions). The description adds value by explaining idempotency ties job_event_id and rating, and clarifies provider_npub's optionality based on context, going beyond the schema.

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

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

The description clearly states 'Rate a completed job' and explains it mirrors web app buttons, publishing a NIP-90 kind 7000 feedback event. It distinguishes from sibling tools like submit_diff_review by specifying the feedback mechanism.

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: use after a completed job, and mentions idempotency and when to call add_contact. It lacks explicit exclusions but covers key usage scenarios well.

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 no annotations provided, the description carries the full burden, and it does so thoroughly. It discloses the disk-loading behavior, the security gate based on the currently active agent rather than the target, the CI environment override, and the persistent effect on subsequent tool calls. This is rich, non-obvious behavioral context that an agent needs before invoking the tool.

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

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

Every sentence earns its place: the first states the core action, the second explains loading, the third covers critical security semantics, and the fourth clarifies downstream impact. The most important information is front-loaded, and there is 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 single-parameter tool with no annotations and no output schema, the description is remarkably complete. It explains what the tool does, how the parameter is resolved, the security constraint, the CI override, and the persistent effect on future calls. Nothing essential is missing for an agent to select and 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?

The schema provides only a required 'name' string with 0% description coverage, so the description must compensate. It does by implying that 'name' identifies the agent to switch to and that this agent may be loaded from disk. It does not explicitly say the name must match an existing configured agent, but for a single obvious parameter, this is adequate guidance.

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 'Switch the active agent,' a specific verb and resource that clearly identifies the tool's function. It distinguishes itself from sibling tools like list_agents or create_agent by focusing on changing the active runtime agent rather than managing or querying agents.

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 makes the usage context clear: call this tool to change which agent will handle subsequent tool calls, with the explicit statement 'All subsequent tool calls will use this agent.' It also notes the security gating and CI override, which clarifies when it may be blocked, though it does not name alternative tools or explicit when-not-to-use scenarios.

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?

No annotations are provided, so the description fully discloses behavior: explains three possible statuses (verified, broken, unverifiable) and their meanings, clarifying that 'unverifiable' is a neutral signal. This provides sufficient transparency.

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 paragraph but packs necessary information efficiently. It front-loads the purpose and then details statuses. Could be slightly more structured (e.g., bullet points), but still concise and clear.

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?

No output schema exists, so the description must explain return values, which it does by describing the three statuses and their significance. It covers the main use case adequately, though it could mention potential limitations like multiple claims.

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 value by explaining the purpose and format of the npub parameter beyond the schema's description, reinforcing what to pass.

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

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

The description clearly states the verb 'Verify' and the resource 'agent's external identity claims'. It distinguishes from siblings like search_agents or get_identity by specifying that it fetches proofs to verify claims.

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

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

Explicitly states when to call ('before hiring when trust matters') and when not to call ('do not call while browsing search results'). Also specifies the required parameter: 'Pass an agent npub'.

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?

Since annotations are absent, the description carries the full burden and does an excellent job: it explicitly outlines the two-step process (preview with nonce, then execute with nonce), the behavior of amount='all' (with the SOL fee reserve nuance), and the legacy alias behavior. It also flags a safety constraint about untrusted content. The only minor gap is not describing the exact response format of the preview or the execution result, but the two-step mechanics are well disclosed, earning a 4 rather than 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?

The description is a single paragraph but packed with essential information, with the primary action stated first and the most critical safety warning last. Every sentence adds value: the gating prerequisite, the two-step flow, the special amount value, and the untrusted-content warning. It is not terse, but the length is justified given the complexity of the tool. A 5 would require tighter formatting (e.g., bullet points), but the content is economically written.

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 (two-step, multiple asset types, gating, legacy alias, and safety implications), the description is remarkably complete. It covers prerequisites, the exact workflow, the meaning of special values, the legacy option, and a security warning. There is no output schema, but the description implies the preview returns a nonce, which is sufficient. An agent could execute the full workflow correctly based solely on this description; no critical details are missing.

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

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

The schema description coverage is 100%, so all five parameters are documented in detail (e.g., amount as decimal string with example, token with enum options, nonce as confirmation). The description adds extra value beyond the schema by clarifying the interplay between parameters: that nonce must be used with the same address/amount/token, that amount='all' has special semantics for SOL vs SPL, and that amount_sol is a legacy alias. This elevation from 3 to 4 is justified because the description provides usage logic 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 states a clear verb ('Withdraw') with a specific resource (SOL, USDC, LSM from the agent's wallet) and a destination address. It distinguishes itself from siblings like get_balance and send_payment by clarifying it moves funds out of the agent's wallet. The description goes beyond a generic statement by explicitly naming the assets and the mainnet constraint for LSM, making the purpose unmistakable.

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

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

The description provides explicit when-to-use guidance: it states the gating requirement (security.withdrawals_enabled), the two-step preview-then-execute flow, and when to use each field (e.g., nonce for confirmation, amount='all' for draining). It also clearly warns against using the tool based on untrusted content, ensuring the agent only acts on explicit user requests. This goes beyond simple context to include concrete exclusions and safety rules.

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