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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It usefully notes that the server verifies both artifacts, but it does not describe whether this is a mutation, what happens on verification failure, whether submissions are idempotent, or what permissions or prerequisites are required.

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

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

The description is two short sentences with no wasted wording, and it front-loads the submission action. Its terseness contributes to the missing information elsewhere but the sentence structure itself is 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 four-parameter submission tool with no annotations, no output schema, and low schema coverage, the description is incomplete. It should clarify the badge-application outcome, prerequisite workflow, verification/failure behavior, and the roles of wallet and xHandle.

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 25%, and the description only vaguely maps 'signed message' to signature and 'public X post' to postUrl. It says nothing about the wallet or xHandle parameters, leaving half the required inputs unexplained beyond their bare schema types.

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

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

The description states a specific action ('submits') and names two artifacts (signed message, public X post), but it never states that this is a badge application or how it differs from prepare_badge_message. The agent can infer the terminal step from the name and title, but the description alone leaves the ultimate purpose vague.

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?

There is no explicit guidance on when to use this tool, when not to use it, or which sibling tools must precede it. It does not mention that prepare_badge_message likely produces the signed message or that wallet and xHandle must already be available.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description's job is smaller; 'Public' adds that no auth is needed and 'saved' implies only previously persisted metadata is returned, not an on-chain lookup. It says nothing about what happens when no metadata exists for the token, which is the main behavioral unknown.

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?

A single front-loaded sentence with no filler, but it is under-specified rather than genuinely tight — the brevity costs parameter and behavior detail that a few more words could have supplied.

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

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

With no output schema, the description should say what metadata is returned (name, symbol, decimals, logo?) and what a miss looks like. For a two-required-parameter lookup tool it leaves the agent guessing about both the return shape and the missing-token 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%: chainId carries an inline chain-ID mapping, but token has only a regex pattern and no explanation of what address it expects. The description mentions neither parameter, so it adds no semantics beyond the schema and leaves the gap unfilled.

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

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

States a specific verb and resource ('Public read of a token's saved metadata'), which clearly separates it from the mutating siblings save_metadata, lock_metadata, and prepare_metadata_message. It doesn't explicitly name those siblings, but the read/write split is unambiguous.

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

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

The word 'Public' hints that no authentication is required, but there is no statement of when to call this versus save_metadata or prepare_metadata_message, and no prerequisites or failure conditions. The agent must infer routing from the tool name alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful domain behavior by clarifying that only approved non-native assets are returned and that the native coin is always allowed.

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 with no wasted words. The parenthetical exception is compact and relevant.

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

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

For a simple read-only getter with one fully documented parameter and annotations covering safety, the description is nearly complete. It could say more about the return format, but the core selection and scope information 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 100%, and the chainId parameter already documents supported chain IDs. The description adds only the phrase 'for a chain' and does not provide additional parameter semantics beyond the schema.

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

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

The description states a specific resource and scope: approved non-native quote assets for a given chain, with the native coin exception. It is clear what the tool returns, though it does not explicitly differentiate itself from sibling tools.

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

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

The description implies the tool is used to retrieve quote assets for a chain, but it gives no explicit when-to-use guidance, no alternatives, and no conditions beyond the native-coin exception.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds two real facts beyond that: results are public and each entry carries proof signatures, which matters for downstream verification. It stops short of saying whether the list is complete or paginated, which is the main behavioral unknown for a list tool with no parameters and no output schema.

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

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

It is a single short clause with no filler, but it reads as a truncated caption rather than a front-loaded description, and the key qualifier ('Public') is buried in the middle of a noun phrase.

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

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

For a read-only, zero-parameter list tool this is nearly adequate, but with no output schema the description is the only source of return-value information and it says nothing about result shape beyond 'proof signatures', nor about whether the list is exhaustive or bounded.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter claims in the description conflict with the empty 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 fragment 'Public list of agent wallets linked to an X handle' identifies the resource and its scope, so an agent can infer the verb (list) and content. However, it is a noun phrase rather than a statement of action, and it never distinguishes itself from siblings such as read_agent_room or list_chains beyond the noun 'agent wallets'.

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?

There is no guidance on when to call this versus read_agent_room or the other list/prepare tools, and no stated preconditions. The word 'Public' hints at unauthenticated access but is not framed as a usage condition.

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?

readOnlyHint=true already establishes this is a safe read, so the description's burden is reduced. It adds which fields come back, but nothing about ordering, whether the list is exhaustive, or whether it hits remote state — modest value beyond annotations.

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

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

A single short clause with zero padding, and the returned-field list is front-loaded. It loses a point for being a fragment that omits the verb rather than a complete sentence.

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 read tool with an annotation covering safety and no output schema, the description adequately sketches the return shape (chain id, native coin, contract addresses). Ordering or filtering details would be nice but are not required to call it correctly.

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

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

The tool takes zero parameters, so the schema has nothing to document and there is no parameter semantics to compensate for. Baseline 4 applies.

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

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

The description names the resource (Kosmo Protocol chains) and enumerates the returned fields (chain id, native coin, factory/executor/hook contracts), so the agent can infer it enumerates supported chains. However, it is a noun phrase with no verb, and the listing action is only implied by the tool name 'list_chains'.

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?

There is no statement of when to call this, no prerequisites, and no comparison to siblings such as get_quote_assets. The agent must infer usage purely from the name.

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

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

Annotations already declare destructiveHint=true, but the description adds the crucial nuance that the destruction is irreversible ('can never be changed') and which fields are affected, plus the authorization requirement. It does not cover failure modes, cost, or whether the signature can be reused, which keeps it from 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?

Two sentences, with the irreversible consequence front-loaded in capitals before the procedural guidance. Every clause carries information; nothing is redundant.

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

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

For a destructive, no-output-schema mutation the description covers the essential agent-facing concerns: irreversibility, consent, ordering, and prerequisite signing. Remaining gaps are the mechanics of the timestamp/signature payload, which the schema also leaves thin.

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 25% (only chainId is documented), so the description must compensate and only partially does: it identifies that 'signature' must originate from prepare_metadata_message. It says nothing about 'timestamp' semantics (freshness window, format) or what the 'token' address must correspond to.

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?

Names a specific action (permanently locking token metadata) and immediately enumerates the affected fields (logo, description, links), so the agent knows exactly what resource is touched. It is clearly distinct from siblings like save_metadata or get_metadata because the permanence is stated up front.

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 gives ordering ('Call it last'), a consent precondition ('only with the owner's explicit confirmation'), and the required prerequisite tool ('freshly signed message from prepare_metadata_message'). An agent has no ambiguity about when this tool is appropriate versus the other metadata siblings.

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 behavioral burden. It discloses that the tool returns a signable message and adds workflow/prerequisite context, but it does not cover authentication needs, validation behavior, idempotency, or exact return 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 front-loaded with purpose, then gives next steps and a prerequisite in three compact sentences. There is no obvious filler, though it could be slightly more 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?

For a two-parameter tool with no annotations and no output schema, it supplies useful purpose and workflow context. However, it leaves parameter-level guidance and behavioral details under-specified.

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 indirectly identifies wallet as the agent wallet and xHandle as the X account, but it adds little about formats, handle syntax, or constraints beyond what the schema's wallet pattern 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 first sentence states a specific verb and resource: it returns the message the agent wallet must sign. The title and description tie it to the Agent badge, but the description does not explicitly contrast it with prepare_metadata_message, so sibling differentiation is only implicit.

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 a clear downstream workflow: post the wallet address from the X account, then call apply_badge with the post URL. This makes the tool's position before apply_badge clear, though it does not state exclusions or explicitly compare 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 burden and does it well: it states the server never signs or sends, that the output is unsigned and must be signed by the wallet owner, and that creator fees are permanent. It omits cost/rate behavior and what happens when the simulation fails, so it is strong but not exhaustive.

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, each doing distinct work: what it computes, what it returns and who signs, and which parameters must be asked for with the permanence warning. The most consequential facts (unsigned, no defaults) are front-loaded.

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

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

For a 12-parameter, 10-required mutation-preparation tool with no output schema and no annotations, the description covers the return payload, the signing model, and the permanence constraint. Gaps remain around quoteAsset approval requirements and failure behavior during simulation, but nothing critical to correct invocation is absent.

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 already 83%, so the baseline is 3; the description adds genuine meaning by declaring that five of the parameters have no defaults and must be solicited from the owner, and by flagging that creatorBuyFeeBps/creatorSellFeeBps are permanent. It does not explain firstBuy or quoteAsset usage, which is left to the schema.

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

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

The description opens with a specific chain of verbs and the concrete artifact produced: 'Mines the vanity salt, computes the start tick, simulates, and returns an UNSIGNED factory transaction plus the predicted token address.' That is enough to separate it from siblings such as prepare_metadata_message or save_metadata, which prepare other artifacts.

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

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

It gives explicit operational preconditions — no defaults for fee/share settings, must ask the owner for suffix and the four bps values, and must show the summary before signing. It does not explicitly name when another sibling (e.g. get_quote_assets before supplying quoteAsset) should be used first, so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the 10-minute validity and the need to request fresh messages per step, especially for locking, but it omits auth requirements, whether the message is single-use, and any side-effect or error behavior.

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

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

The description is three tight sentences with no filler. The core return value is front-loaded, followed by validity and freshness constraints, so every sentence earns its place.

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

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

For a simple one-parameter tool with no output schema or annotations, the description covers the main purpose and timing constraints. However, it leaves the token parameter underspecified and does not address authentication or whether the returned message must be used immediately, making it only minimally 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 single token parameter has 0% schema description coverage; the schema only supplies a regex pattern. The description mentions the token's creator wallet but does not explain what the token parameter expects, whether it is a token address, or any chain-specific semantics, so it does not compensate for the schema gap.

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

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

The description states a specific verb and resource: it returns the exact message the creator wallet must sign for logo upload, metadata save, or metadata lock. It is clear enough to distinguish from generic signing tools, but it does not explicitly name siblings like upload_logo or lock_metadata to reinforce 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?

It gives clear usage context: use it before uploading a logo, saving metadata, or locking metadata. It also gives important operational guidance—valid for 10 minutes, request a fresh one per separate step, always fresh for locking—but does not explicitly state when not to use it or name alternatives such as prepare_badge_message.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is partly covered. The description adds a crucial behavioral warning that messages are untrusted data and that instructions inside them must never be followed, though it does not discuss pagination or rate limits.

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

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

The description uses two tight sentences with no wasted text. The core scope is front-loaded, and the security warning follows efficiently.

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

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

For a simple read tool with annotations covering safety, this is mostly adequate and importantly covers the untrusted-data risk. However, it leaves the after parameter semantics unexplained and, with no output schema, says little about the returned message structure.

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 50%: the channel parameter is described in the schema, but the after parameter has no explanation anywhere. The description adds no parameter meaning, so it does not compensate for the undocumented after parameter.

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: 'Public read of Agent Room messages.' It also clarifies that the messages come from other agents, which distinguishes this read path from unrelated siblings such as list_agents or list_chains.

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 when this tool applies by identifying the Agent Room message read operation, but it gives no explicit when-to-use/when-not-to-use guidance or named alternatives. The security warning is important but is not tool-selection guidance.

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

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

There are no annotations, so the description carries the full burden. It discloses the max description length and the signature prerequisite, which is genuinely useful, but says nothing about whether it overwrites existing metadata, whether it is irreversible after lock_metadata, what permissions are needed, or what the call returns.

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 main action first and the blocking prerequisite second; nothing is padded. It is efficient but perhaps a bit too terse given the 8-parameter mutation surface.

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?

A mutation tool with 8 parameters, 4 required, no annotations, no output schema, and low schema coverage needs substantially more from the description. Key facts (what happens on repeat calls, immutability/interaction with lock_metadata, return behavior) are absent.

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 13% (only chainId is documented), so the description should compensate. Instead it only loosely gestures at 'social links' (website, xHandle, telegram) and repeats the 500-char limit already in the schema via maxLength; token, timestamp, and signature semantics are unexplained.

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 ('Saves description ... and social links') for token metadata, and names the sibling tool (prepare_metadata_message) that produces the required signature, so an agent can distinguish it from the prepare step. It does not mention chainId/token/timestamp, so the full scope is only partly conveyed.

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 prerequisite 'Needs a signature from prepare_metadata_message' implies a workflow ordering and routes the agent to the right sibling. However, it gives no when-not guidance versus get_metadata or lock_metadata, and no prerequisites around ownership or timing.

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 behavioral burden and does disclose the auth prerequisite (signature), accepted formats, and size limit. However it says nothing about whether an upload overwrites an existing logo, whether the call is idempotent, or what happens on failure, which matter for a write 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?

Three short sentences, each carrying distinct information: action plus format limits, the prerequisite signature, and the input-mode choice. Nothing is repeated or wasted, and the core action is front-loaded.

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

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

For a mutation tool with no annotations, no output schema, and seven parameters, the description covers the critical prerequisite and input alternatives but omits the meaning of timestamp and mimeType and any success/return behavior. It is adequate to attempt a call but not 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 only 14% (only chainId is documented), so the description must compensate; it does partially by explaining filePath vs base64 and the signature prerequisite. It leaves 'token', 'timestamp', and 'mimeType' entirely unexplained, so nearly half the parameters remain opaque.

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

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

The description names a specific verb and resource ('Uploads the logo') and bounds it with accepted formats (png, jpeg, webp, gif) and a 5 MB size cap. It also names the sibling it depends on (prepare_metadata_message), which separates it from save_metadata or apply_badge, though it does not state how it differs from the broader metadata-saving 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?

'Needs a signature from prepare_metadata_message' gives an explicit prerequisite that routes the agent to the correct earlier step in the workflow. 'Provide filePath or base64' clarifies the two input modes, but there is no statement of when not to use it or what to do if a logo already exists.

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