Surgemesh

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

No annotations are supplied, so the description carries the full burden. It does disclose a useful side effect (undelivered deliveries refunded to credit), but omits whether cancellation is irreversible, what permission level is required, and what happens to partially delivered posts. Real value added, but meaningful gaps remain for a destructive 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 short sentences with zero waste, and the action statement is front-loaded ahead of the refund side effect.

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, no-output-schema tool this covers the core action and its credit refund consequence. An agent would still want to know failure modes and irreversibility, but nothing essential is missing for invocation.

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

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

One parameter (id) with 0% schema description coverage. The description implies the id identifies a queued post, but never says so explicitly or specifies the identifier format (post UUID vs. numeric). Modest inference required beyond the bare 'string' type.

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 (cancel) and a specific scoped resource (a queued post), which is unambiguous against siblings like create_post and list_posts. It does not explicitly say what it is not, but no sibling overlaps in function.

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 'queued' implies the precondition that only unsent posts can be cancelled, but the description never states what happens when a post is already sent or in flight, nor does it name an alternative path. Usage is inferable rather than 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?

With no annotations, the description carries the full burden; it usefully discloses a side effect ('verifies the account when it is'), which tells the agent this is not a pure read. However it omits what happens on failure, whether the check is idempotent or safe to repeat while DNS propagates, and whether verification is consumed.

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 clauses with the action front-loaded and the outcome second; no filler. It is arguably over-compressed rather than padded, but structurally sound.

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 output schema, the description is minimally adequate: it conveys purpose and the key side effect. It leaves gaps on the parameter's origin, failure/retry behavior, and what a negative result looks like, which an agent needs to call this correctly in a verification flow.

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?

One required parameter (verification_id) with 0% schema description coverage, and the description never mentions it. The agent must guess where verification_id comes from (presumably start_dns_verification) and its format. The description 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?

States a specific check action on a specific resource (TXT record visibility) and the resulting effect (account verification). It is distinguishable from start_dns_verification and get_verification by the 'check' semantics, though it never names those siblings explicitly.

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 only implied: an agent can infer this runs after start_dns_verification has issued the TXT record. There is no explicit statement of when to call this versus get_verification or confirm_email_verification, and no prerequisites or timing guidance (e.g., DNS propagation delay).

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 must carry the behavioral burden. It states the submission action but omits side effects, expiration behavior, invalid-code handling, and what successful confirmation means, leaving significant gaps for a verification mutation 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 a single front-loaded sentence with no wasted words. It immediately tells the agent the action and the required input.

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 two required parameters, no output schema, and no annotations, the description is too thin. It does not explain verification_id, expected success or failure outcomes, or the relationship to start_email_verification, leaving the agent without key context.

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

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

Schema description coverage is 0%, so the description should compensate. It clarifies that 'code' is the 6-digit code from the email, but it provides no explanation of 'verification_id', where to obtain it, or how the two parameters relate.

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: submit the 6-digit code from the verification email. This clearly identifies the action as completing email verification, but it does not explicitly distinguish itself from sibling tools like start_email_verification or get_verification.

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 phrase 'from the verification email' implies the tool should be used after receiving a verification email, but there is no explicit guidance on prerequisites, when not to use it, or how it relates to sibling tools such as start_email_verification.

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 reasonably well: it reveals the asynchronous hand-off pattern (a URL the account owner must open once) and the follow-up polling requirement, which are the non-obvious behaviors of this flow. It omits side effects on existing connections, permission/scope requirements, and what happens on a duplicate connect.

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, zero waste: action first, return contract second, next step last. Every sentence carries load and the ordering matches how an agent needs the 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 tool with no output schema and no annotations, the description covers the essential contract (what it returns, who consumes it, what to call next). It leaves gaps around error/already-connected behavior and the undocumented 'label' parameter, but nothing that would cause an obviously wrong call.

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 the nested 'options' object is documented in the schema. The description implicitly conveys brand_id ('for a brand') and network (enumerated in schema, and the phrase 'OAuth or app-password network' hints at network family), but 'label' is never mentioned and the brand/network semantics are not enriched beyond the field names.

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 ('Start') plus the exact resource ('a one-tap connect for a brand on an OAuth or app-password network'), which is far more informative than the bare name. It implicitly separates itself from get_connect_status (the polling step) and disconnect_channel, so an agent can place it in the connect lifecycle 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?

Explicitly prescribes the downstream sequence: hand the returned connect_url to the account owner to open once, then poll get_connect_status. That is a clear when-and-how-to-continue instruction naming the sibling tool. It stops short of stating exclusions or prerequisites (e.g. what to do if the channel is already connected, or that network options come from list_networks).

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 behavioral burden and does well: it discloses the feature is coming soon, returns a Stripe-hosted checkout_url, requires a verified owner/admin key, delays credits until Stripe confirmation, and returns 503 checkout_not_enabled until enabled. Minor gaps like link expiry or rate limits remain, but the key operational traits are present.

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

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

The description is dense and front-loaded, putting the core action and return value first before pricing, payer instructions, auth, and availability caveats. It is appropriately sized for the amount of operational context, though the parenthetical pricing makes it slightly cramped.

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, no-annotation tool without an output schema, the description covers what is returned (checkout_url), the feature's availability (coming soon, 503 until enabled), auth requirements, and post-payment behavior. It is nearly complete, with only minor operational details like link expiry left unstated.

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 50%: the idempotency_key parameter is documented in the schema, while the pack enum is not described there. The description adds useful pricing and intent for pack_5, pack_20, and pack_100, but does not further explain the idempotency key's behavior beyond what the schema already says.

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 that this creates a Stripe-hosted checkout URL for a credit pack intended for a human payer, which is a specific verb and resource. It could more explicitly distinguish itself from sibling tools like get_topup_link, but the card-checkout framing 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?

It gives meaningful usage context: use this for a human paying by card, give the link to that person, and credits arrive only after Stripe confirms. However, it does not explicitly say when to choose this over sibling alternatives such as get_topup_link, and the 'coming soon' state is noted but not tied to a routing decision.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose two meaningful traits: idempotent retry semantics and a surge-price refusal cap. It omits permissions/auth requirements, whether immediate (non-scheduled) publishing is possible, failure behavior beyond the price cap, and the response shape.

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

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

Three tight sentences, front-loaded with the core action, then the mandatory idempotency constraint, then the optional price cap. No filler and no repetition of the schema.

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

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

For a 7-parameter mutation tool with no annotations, no output schema, and 0% schema coverage, the description leaves too much unsaid: channel formats, scheduled_at semantics, media constraints, and authorization are all missing. What it does cover (idempotency, price cap) is high-value but insufficient.

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, and it only explains 2 of 7 parameters (idempotency_key and max_price_usd). The required body, brand_id, channels, scheduled_at, and optional media_urls get no semantic explanation, leaving most of the schema ambiguous.

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: 'Schedule a post to one or more channels.' The word 'schedule' usefully distinguishes it from siblings like list_posts and cancel_post, though it never explicitly names competing tools or clarifies it is the sole creation path.

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

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

Gives implicit usage guidance around retries ('retries with the same key never double-post') and surge pricing, which tells an agent how to behave on retry. However, there is no explicit when-to-use vs alternatives, no prerequisites, and no statement about when a post should be cancelled or listed instead.

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

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

With no annotations, the description carries the full burden and does disclose the critical destructive effects: stored credentials are erased and the provider token is revoked, with the honest caveat 'where the network supports it'. It stops short of stating irreversibility, whether the channel record/posts survive, or what auth level is 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?

A single well-formed sentence with the action front-loaded and the consequences attached; no filler whatsoever.

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, annotation-free mutation with no output schema, the description covers the main side effects but omits irreversibility, how partial failure behaves when the network does not support token revocation, and what a successful response indicates — gaps an agent would want before calling it.

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

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

Schema coverage is 0% for the single required parameter, so the description would need to compensate — it adds nothing about whether channel_id is the internal id from list_channels or a provider-side identifier, nor any format hints. The parameter name is fairly self-explanatory, keeping this at a minimum-viable 3.

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 ('Disconnect a channel') and immediately qualifies the effect (credential erasure, token revocation), making it trivially distinguishable from the sibling connect_channel. An agent knows exactly what this does without opening the schema.

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

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

Usage is only implied by the name's opposition to connect_channel; there is no explicit when-to-use guidance, no mention of alternatives (e.g. using list_channels to obtain channel_id, or rotate_my_key for credential refresh), and no statement of prerequisites or when not to use it.

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 adds useful context by specifying UTC time and per-brand breakdown, but it does not disclose permissions, read-only nature, pagination, rate limits, or return format details.

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

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

The description is a single, dense sentence with no filler. It front-loads the metrics and ends with the per-brand breakdown scope, making efficient use of limited space.

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 analytics tool with no annotations, no output schema, and no schema descriptions, the one-sentence description is insufficient. It omits critical details such as date range behavior, granularity semantics, and expected response 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 coverage is 0% and the description does not explain the four parameters. It hints at date range and brand filtering through 'over time (UTC)' and 'per-brand breakdown', but does not address granularity or clarify formats and defaults.

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 analytics content: posts, deliveries, published, failed, spend, dynamic-pricing usage over time, and per-brand breakdown. It lacks an explicit verb and does not differentiate from close siblings like get_usage, but an agent can still infer the tool's purpose accurately.

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 such as get_usage or list_brands. It only states what data is returned, leaving usage context entirely implicit.

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

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

With no annotations, the description carries the full burden. It usefully discloses the possible states and the presence of channel_id when connected, but it does not state whether the operation is read-only, what permissions are needed, or how errors are surfaced.

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. Every element—resource, operation, and status enumeration—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 adequately conveys the main return states, but it leaves the parameter undefined and gives no guidance on interpreting each status. For a simple get operation with no output schema or annotations, this is minimally complete but has clear gaps.

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

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

The single parameter connect_id is undocumented in both the schema (0% coverage) and the description. The description implies it identifies a connect session, but adds no format or source information to 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 clearly identifies the resource (connect session) and the operation (retrieve status), and it enumerates the possible status values. It does not explicitly differentiate from siblings like connect_channel or disconnect_channel, but the purpose 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?

No guidance is given on when to use this tool versus alternatives, nor are prerequisites or exclusions mentioned. The usage is only implied by the tool name and description.

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 has to carry the full disclosure burden, and it does useful work by revealing the return composition and, importantly, that the response identifies 'the exact next call' — a real behavioral trait that tells an agent this tool drives a workflow. It does not explicitly state that the call is read-only or that state is unchanged, which is the only notable gap for a zero-parameter getter.

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 tight sentences with zero filler, and the most decision-relevant information (what you get, when to call it) 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?

With no output schema, the description must convey the shape of the return value, and it does so by listing the three payload components. It could go slightly further on format (e.g., what 'exact next call' looks like) but is otherwise sufficient for an agent to invoke and interpret it.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The schema is an empty object with additionalProperties false, matching the description's implied no-argument usage.

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 (onboarding status) and enumerates exactly what it returns: verification state, remaining steps, and the next call. 'Start here after signup' also implicitly separates it from downstream verification tools such as get_verification or check_dns_verification, though it never names a sibling explicitly.

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?

'Start here after signup' gives clear entry-point guidance for when to reach for this tool. It stops short of stating exclusions (for example, that later checks should use get_verification instead), but the sequencing intent is unambiguous.

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

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

With no annotations, the description carries the full disclosure burden. It usefully states that no authentication is required, which is the most important operational fact, but says nothing about whether prices are live or cached, account-specific, or what the response looks like.

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 compact sentence with the content list front-loaded ahead of the auth note. It is telegraphic fragments rather than prose, but nothing is wasted.

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-argument lookup with no output schema, enumerating the three returned pricing categories plus the auth requirement covers most of what an agent needs. Currency/format and whether values vary by account are the remaining gaps.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; 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 precisely and enumerates its contents (base per-delivery price, dynamic pricing rules, credit packs), so an agent knows exactly what data comes back. It does not distinguish itself from the sibling get_quote, which an agent must infer is a per-order quote rather than the static price catalog.

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 only implied: you call this to look up pricing. There is no explicit when-to-use or when-not, and no routing away from get_quote despite that sibling existing. The 'No auth needed' note does at least signal that it is freely callable.

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 usefully discloses that pricing is not locked until a post is accepted and that cheaper nearby slots are returned when surging, but it says nothing about quote expiry, auth requirements, or what the returned price structure looks like.

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 dense sentence with the resource and key scoping constraint front-loaded; no filler. The parentheticals pack in a lot but remain readable.

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 annotations and no output schema, so the description should describe the shape of what comes back; it only hints at surge-adjacent cheaper slots. Enough to select the tool and pass parameters, but not enough to know what the response contains or how long a quote stays valid.

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 must compensate, and it does: scheduled_at is clarified as a 15-minute slot anchor and deliveries as a count (N) of deliveries. The mention of max_price_usd, which is not in this tool's schema, risks mild confusion but reads as a guard for the downstream create_post call.

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

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

States a specific verb+resource: a price quote for N deliveries in the 15-minute slot of scheduled_at. It implicitly separates itself from get_pricing by framing the quote around delivery slots and surge behavior, but never names the sibling, so the differentiation is inferential rather than explicit.

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

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

"Locks at post acceptance" and "guard with max_price_usd" imply the quote is fetched before creating a post, giving an implied workflow. However, no explicit when-to-use vs. get_pricing, no prerequisites, and max_price_usd is not even a parameter on this tool, so the guidance is suggestive rather than actionable.

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 supplies important behavioral context: verified-owner authorization, reward policy (Surgemesh credits only, never cash, coming soon), and the returned stat categories. It still does not explicitly state read-only/no-side-effect behavior or rate limits, leaving a minor transparency 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?

The returned resource is front-loaded, followed by compact policy and eligibility caveats. The wording is tight and every sentence adds useful information without 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 zero-parameter getter with no output schema, the description explains the returned fields and the key eligibility and business constraints. It is complete enough for an agent to call correctly, with sibling routing being the only notable omission elsewhere.

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

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

There are zero parameters and the schema is empty, so there is no parameter semantics to document beyond the baseline. The description's 'Your' implies the code is tied to the authenticated owner but introduces no undocumented inputs.

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 enumerates the specific resource contents: referral code, share link, and stats such as signups, qualified referrals, and credits. The purpose is clear, but it uses a noun phrase rather than an explicit verb and does not differentiate itself from sibling get_* 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 gives clear eligibility context with 'Verified owners only' and clarifies current availability: codes can be shared now while rewards are coming soon. It does not name alternatives or explain when another sibling such as get_analytics or get_usage would 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses that no payment is processed here, that the returned link requires a Bearer key and a 402 challenge retry flow, and that each rail shows live or coming_soon status; remaining gaps include rate limits or idempotency 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 response is front-loaded with the core purpose and then layers in pricing, rails, and post-link workflow without obvious filler. It is dense and somewhat long for a single paragraph, but each detail is relevant to using the tool correctly.

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, but the description implies the return value is a payment link and explains the subsequent payment workflow. It lacks details such as the link format or expiration, and does not clarify the optional rail parameter, but it is otherwise complete for this tool's complexity.

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

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

With 0% schema description coverage, the description compensates well by mapping every pack enum to a price and every rail enum to a payment network or method. It does not clarify whether rail is optional or what the default rail is, but it adds substantial meaning beyond the raw enums.

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 returns a payment link for buying credit packs, and it names the pack tiers and prices. It does not differentiate from sibling tools such as create_checkout_link, but the core purpose is still specific and easy to understand.

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 opening phrase establishes the use case: obtaining a payment link to buy a credit pack. It also clarifies that no payment happens in this tool, but it does not explicitly compare this tool against alternatives like create_checkout_link or state when it should not be used.

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 of behavioral disclosure. It implies a read-only account usage lookup by naming data fields, but does not state authentication requirements, data freshness, ledger scope, or whether the response is paginated, leaving 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 fragment with no wasted words and front-loads the returned data. However, it reads as a noun list rather than a complete statement of purpose, which slightly weakens structure.

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

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

With no output schema, the description should do more to explain the return values. It lists the main fields (plan, credits, free deliveries left, recent ledger) but gives no structure, units, or detail about the ledger contents, so it is adequate but incomplete for an agent relying on it to understand the response.

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

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

The tool has zero parameters, so there are no parameter semantics to explain. The description does not need to compensate for schema gaps, making the baseline of 4 appropriate.

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

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

The description clearly identifies the resource as account usage data, naming plan, credits, free deliveries, and recent ledger. It lacks a verb and does not explicitly differentiate itself from siblings like get_analytics or get_pricing, but the returned content is specific enough to distinguish it as the account usage/billing snapshot tool.

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 such as get_analytics, get_pricing, or get_quote. The implied use case is retrieving account usage, but there is no explicit context, prerequisite, or exclusion 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?

With no annotations, the description carries full burden; it does disclose the closed set of possible status outcomes (pending, verified, expired, failed, denied), which is genuinely useful behavior information. However it says nothing about read-only safety, authentication needs, rate limits, or whether the result is a snapshot versus live state.

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?

One short sentence with the status enumeration placed inline, no filler. It is efficiently sized, though the terseness borders on under-specification rather than genuinely economical prose.

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, no annotations, and an undocumented required parameter mean the description should do more. It omits where the verification_id comes from, whether the call is safe/read-only, and how the returned status maps to next actions (e.g., retry versus give up on failure/expired).

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 single required parameter verification_id is undocumented in both schema and description. The description does not explain where to obtain a verification_id (presumably from start_dns_verification or start_email_verification) or its format, leaving the only parameter's semantics unaddressed.

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 (one verification) and the aspect being retrieved (its status), and enumerates the possible states. It is clear what the tool returns, though it never uses an explicit verb and does not distinguish itself from siblings like check_dns_verification or confirm_email_verification.

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 use this lookup versus check_dns_verification, confirm_email_verification, or the start_* tools, and no mention of prerequisites or polling guidance. The agent must infer usage entirely 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?

No annotations are provided, so the description carries the full disclosure burden, yet it says nothing about read-only safety, authentication requirements, pagination, ordering, or the shape of what comes back. It is a low-risk zero-parameter read, which limits the damage, but essentially no behavioral context is offered.

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 certainly short and front-loaded, but it is under-specified rather than concise: a single fragment that omits even a verb. Brevity here costs information rather than saving it.

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 at least say what a brand record contains or whether results are paginated, and it does neither. For a simple list tool this is a moderate rather than fatal gap, but an agent learns nothing about the return value.

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 clarify and the baseline of 4 applies. No parameter-related gaps exist.

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

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

The description names the resource (brands) and its scope (in this account), which distinguishes it from a hypothetical global brand lookup. However, it is a noun fragment with no verb, and it does not differentiate itself from the many other list_* siblings (list_channels, list_networks, list_posts) beyond naming a different resource.

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 tool, what it is needed for, or which alternative to use when brands are not the desired resource. The agent must infer usage entirely 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?

With no annotations, the description carries full behavioral burden and falls short. It does not state that the operation is read-only, what permissions are required, whether disconnected channels are excluded, or what the return shape looks like.

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 short phrase with no wasted words and puts the resource definition first. It is appropriately sized for a simple zero-parameter list tool, though it is a sentence fragment rather than a structured explanation.

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 no-parameter listing tool, the description is minimally sufficient to indicate what is returned conceptually. However, with no output schema or annotations, it could do more to explain return values, ordering, or whether all connected accounts are included.

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. There are no parameter semantics to explain, and the description does not need to compensate for schema gaps.

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 specific resource ('channels') and clarifies it means connected social accounts available to this key. It implies a listing operation and scopes the result to what the key can post to, though it relies on the tool name for the verb.

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 no explicit guidance on when to use this tool versus siblings such as list_networks, connect_channel, or disconnect_channel. The phrase 'this key can post to' hints at discovering posting targets, but no alternatives or exclusion conditions are 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?

With no annotations, the description carries the burden and does well: it discloses that no auth is required and that the result surfaces status values including connect_pending_review and connect_pending_setup, which hints at workflows. It never explicitly says 'read-only', but listing networks inherently signals it.

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 compact sentence with the resource front-loaded and field details after. It is dense but every clause earns its place by naming a returned field category.

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 or annotations exist, so the description must explain the return value — and it does by listing status enum values and the categories of data (connect steps, review limits, cost notes, media limits). Minor gap: no statement of ordering or volume of networks.

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

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

Zero parameters, so there is nothing to document; the baseline is 4. The description correctly omits param discussion and instead describes what the parameterless call returns.

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 resource ('Every supported network') and enumerates what each entry contains (status, how to connect, review limits, cost notes, media limits). An agent can distinguish this from list_brands/list_channels by the 'network' resource, though it never names a sibling explicitly.

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 only usage signal is 'No auth needed' plus the implied use case of discovering networks before connecting. There is no explicit when-to-use or when-not-to-use versus alternatives like list_channels or connect_channel.

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 behavioral burden. It mentions per-channel delivery state but does not disclose read-only nature, pagination, ordering, recency bounds, authentication requirements, or return structure.

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 tight sentence with no wasted words. The key qualifiers—recent, brand-scoped, per-channel delivery state—are front-loaded and each 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 tool is simple with one required parameter and no output schema, so the description is minimally viable. However, it omits important context for interpreting results, such as pagination limits, ordering of 'recent' posts, and the shape of per-channel delivery state.

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 implies the single parameter is a brand identifier via 'for a brand', but does not explain the expected ID format, where to obtain it, or any validation semantics.

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

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

The description clearly identifies the resource ('posts') and scope ('recent posts for a brand') and hints at included data ('per-channel delivery state'). It is distinguishable from sibling mutation tools like create_post and cancel_post, though it does not use an explicit verb such as 'list'.

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 no explicit guidance on when to use this tool versus alternatives such as get_analytics or create_post. Usage is only implied by 'recent posts for a brand'; there are no exclusions or conditions.

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 well: it discloses the outbound email, the 24-hour TTL, and single-use semantics, which are exactly the traits an agent cannot infer. Gaps remain on permissions required, behavior when a request is already pending, and what the call itself returns (e.g., a request id to correlate polling).

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, zero filler, with the action and its constraints front-loaded before the follow-up instruction. Every clause 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 is complete on the side-effect and lifecycle (email, TTL, single use, polling), which is the hard part for an unannotated tool. But with no output schema and low parameter coverage, an agent still cannot tell what the call returns, how failures are surfaced, or what the optional parameters do — so it is adequate rather than 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 only 33% — just idempotency_key is documented — and the description adds nothing about `note` (the message shown to the owner) or `callback_url` (where a result is posted). With two of three parameters undocumented in both places, the description fails to compensate for the 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?

States a specific verb and resource ('Email the account owner a one-tap Approve link') plus mechanism-level detail: 24-hour expiry, single use. It is distinguishable from siblings like start_email_verification or get_verification without opening any schema.

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

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

Gives concrete sequencing guidance — 'Poll get_verification until verified or denied' — which tells the agent what to do after the call. However, it never states the conditions that select this tool over alternatives (e.g., when an approval escalation is warranted vs. direct verification flows) or any prerequisites.

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

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

No annotations are provided, so the description carries the full burden and does it well: it discloses that the new key is shown only once, that it inherits the same scopes, and that the old key remains valid for grace_seconds with 0 meaning immediate revocation. Those are exactly the non-obvious, irreversible-ish traits an agent needs before calling a credential mutation.

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 sentence, front-loaded with the action, then the return value, then the parameter semantics in parentheses. No sentence is wasted and nothing important trails off.

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 mutation with no output schema and no annotations, the description covers the action, the returned artifact, and the key parameter's contract. It leaves unstated whether the new key is immediately active and whether other existing keys are affected, which matters for an agent reasoning about blast radius.

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 50%: idempotency_key is documented in the schema, but grace_seconds is not. The description compensates by defining grace_seconds' meaning, its default (3600) and the special value 0, which is more than the schema alone offers. It does not mention the 0–86400 bounds, so it doesn't fully close the 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?

States a specific verb and resource ('Rotate the calling key') and immediately scopes it to the caller's own key, which no sibling tool touches. An agent can distinguish it from every listed sibling without opening the schema.

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

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

Usage is implied by the name and the 'revoke now' hint (use with grace_seconds=0 to immediately kill the old key), but the description never says when an agent should rotate versus simply continue using the existing key, nor whether any prerequisite/confirmation exists. With no sibling alternatives to route between, implied usage is the realistic ceiling here.

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 disclosure burden, and it does not mention that this call creates a pending verification state on the account, what happens on repeated calls, whether the issued record expires, or what permissions are required. It reads like a benign read ("Get a TXT record") while the tool actually initiates a verification process — without annotations there is nothing to correct that impression. Idempotency is handled only in the schema, not in 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?

Two short sentences with zero waste: the deliverable and its placement constraint first, the required follow-up call second. Nothing is buried and nothing is repeated.

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 should say more about what comes back beyond "a TXT record" (host/name label, expected value, TTL) and how the agent should report success or failure. It is adequate for a 2-parameter tool and correctly delegates the next step, but for a state-changing verification flow with no structured metadata it leaves real gaps.

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

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

Schema coverage is 50%: idempotency_key documents itself fully, while domain is a bare string in the schema. The description compensates by specifying that domain must be the account email domain or a parent domain, which is genuine semantic value the schema does not provide. Remaining minor gap is that it doesn't clarify formatting (bare domain vs URL) for the domain 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 names the concrete artifact produced (a TXT record) and the domain scope it must belong to, so the agent knows this kicks off DNS-based verification. It also distinguishes itself from the follow-up sibling check_dns_verification. It stops short of stating the action in its own terms (initiate verification) and never contrasts with start_email_verification, but the resource 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?

"Then call check_dns_verification" explicitly sequences the next step, which is the single most important routing hint for this tool. The parenthetical "(or a parent domain)" tells the agent what input is acceptable. What's missing is when NOT to use this path — with start_email_verification as a sibling, the agent gets no rule for choosing between the email and DNS verification flows.

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 and does disclose meaningful behavior: the code is sent to the account email (the caller cannot choose a destination), it expires in 10 minutes, and there are 5 attempts. It omits whether calling again resends or invalidates an outstanding code, and says nothing about rate limits or failure/error modes for a mutation that produces an email.

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, both earning their place: the first states the action plus its operational constraints, the second states the required follow-up. Nothing is repeated from the schema or padded.

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 low-complexity, zero-required-parameter starter tool with no output schema, the description covers the action, the constraints that shape agent retry logic, and the mandatory next call. It lacks only what a successful response looks like (masked email, expiry echo) or what error states to expect.

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

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

There is a single optional parameter, idempotency_key, and the schema already documents it at 100% coverage with a clear retry instruction. The description adds no parameter-level meaning, which matches the baseline of 3 when schema coverage is high.

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 ('Email a 6-digit code to the account email') and implicitly scopes the destination to the account's own address. The second sentence names the sibling confirm_email_verification and its role, so an agent can separate the two-step flow from the other verification siblings (start_dns_verification, get_verification) without opening a schema.

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

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

Explicitly tells the agent this is step one of a sequence and that confirm_email_verification must be called next with the code, which is the key routing rule. It does not state preconditions (e.g. authenticated account, no verification already pending) or when to prefer start_dns_verification instead, so it stops short of full when/when-not guidance.

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