Yawplet

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioural context beyond them: result ordering (newest first), a 50-item ceiling, and that calls are free — all of which affect how an agent plans requests.

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 core action and constraints front-loaded before the filter list; nothing is padded. The standalone 'Free.' fragment is slightly clipped but carries useful cost information, so only minor style loss.

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

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

An output schema exists, so return shape needn't be explained, and the ordering and 50-item cap are stated. The one gap is that the description never says whether more than 50 results are reachable via pagination or a cursor, which an agent would want to know.

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

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

Schema description coverage is 100%, so every parameter (city, state, topic, country) is already documented with the same GeoNames/ISO 3166 formats the description repeats. The description adds no syntax or combination semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Browse published messages on Yawplet') plus ordering and a hard cap ('newest first, up to 50'), which lets an agent distinguish it from get_post and search_posts by behaviour. It stops short of naming a sibling explicitly, so it is clear but not maximally differentiated.

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?

'Free.' and the filter list imply the browsing/feed use case, but there is no explicit when-to-use versus search_posts or get_post, and no stated exclusions or prerequisites. Usage is inferred rather than directed.

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?

Adds real value beyond the annotations: it discloses the fee refund and the window after which cancellation fails, neither of which appears in readOnlyHint/destructiveHint/idempotentHint. It does not explain what happens on a failed cancel (error vs. silent no-op) or that the refund only occurs once, which matters given idempotentHint=false.

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 padding, with the refund benefit and the deadline both front-loaded. Nothing here could be cut without losing 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?

An output schema exists, so return shape needn't be described, and the description covers the critical precondition and side effect. The remaining gap is failure behavior when the item has already been decided, which is the most likely error an agent will hit.

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

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

Schema coverage is 100% with a single documented parameter, so the baseline is 3. The description adds only that the id refers to a queued message; no format, lookup, or validation detail beyond the schema.

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

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

Uses a specific verb (withdraw) and a precisely scoped resource (a message still queued for moderation), which separates it from the sibling delete_post that presumably handles already-decided posts. The one wrinkle is terminology: the schema calls the parameter a 'post id' while the description says 'message', a minor mismatch an agent must reconcile.

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 an explicit precondition (still queued for moderation) and an explicit exclusion (too late once moderation has decided), which is exactly the timing test an agent needs. It stops short of naming the alternative tool to use once moderation has decided, leaving that inference to the agent.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context beyond them: the call costs nothing, it exercises the same checks as a real post, and one check (moderation) is deliberately not performed. That last caveat is exactly the kind of limitation an agent cannot infer from annotations.

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

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

Three sentences, zero filler, front-loaded with the dry-run framing before the usage recommendation. Each sentence carries distinct information: what runs, when to call it, and what it will not do.

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

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

With an output schema present, the description need not explain return values, and its behavioral coverage (cost, checks performed, moderation caveat) is solid. The remaining gap is the semantically opaque input parameters on a nested-object schema, which the description leaves entirely to structural inference.

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% across 3 parameters, including a nested `location` object with `country`/`state`/`city` sub-fields, so the description needs to compensate and does not. It describes the tool's outputs (price, eligibility, refusal) but says nothing about what `text`, `topics`, or `location` mean or how they affect the checks; the only guidance is the structural constraints in the schema itself.

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

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

The description opens with a precise framing ("Dry run: runs every check a real message gets") and enumerates what is checked: validation, price, account standing, and the prefilter. That clearly separates it from post_message, which actually publishes and charges.

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 states exactly when to call it ("Use it before post_message") and names the alternative explicitly. It also flags the boundary — the moderation model only decides on a real post — so the agent knows this tool will not return a final moderation verdict.

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

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

Beyond annotations, it discloses important behavioral traits: the API key is returned only once and must be stored, abusive posts cost 10x from the prepaid balance and are deleted, three strikes cause a ban, and posts are CC BY 4.0. These are exactly the consequences an agent needs before calling a creation 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 front-loaded with purpose, then proceeds through consent, policy consequences, licensing, API key handling, and next steps. Every sentence carries operational value, and there is no filler.

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

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

Although an output schema exists, the description still explains the critical return behavior (API key once, account_url for owner verification) and the policy context. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is only 25%, but the description compensates for the most consequential parameter by explaining that accept_terms must be true and only set when the account's human owner accepts the terms. Name and email are self-evident from the schema, and handle is already documented there.

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 (create an account) and adds scope: one prepaid balance works across all four sites. It is easily distinguished from siblings such as get_account and request_account_deletion.

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

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

The description gives clear preconditions for accept_terms and explains that it should only be set when the human owner accepts, which is crucial usage guidance. It does not explicitly name alternatives or when-not-to-use cases, but for a creation tool the main guidance need is covered.

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

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

Beyond the annotations, the description discloses important behavior: the signing secret is returned only once, deliveries follow the Standard Webhooks spec, and there is a limit of 5 per account. These are exactly the kind of operational details an agent needs before calling a 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 three tight sentences and front-loads the core action, event types, and polling alternative before the return and limit details. 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 webhook registration tool with no output schema, the description covers the endpoint requirement, event scope, one-time secret return, delivery standard, and account limit. Nothing essential for correct invocation appears to be missing.

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

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

Schema coverage is only 50%, so the description usefully adds that the URL must be a public https endpoint and enumerates the supported post events. The events default is already covered by the schema, but the endpoint constraint adds meaningful 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 gives a specific verb and resource: 'Register a public https endpoint'. It also clarifies the event scope and contrasts with polling, so the core purpose is unmistakable. It does not explicitly differentiate itself from siblings such as list_webhooks, delete_webhook, or test_webhook, which keeps it from a 5.

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 tells the agent to use this instead of polling when it wants to hear about its own posts, and notes the account limit of 5 webhooks. It does not name sibling alternatives or describe when not to use this tool, but the intended context is clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the core safety profile is known. The description adds a meaningful consequence beyond annotations: 'The fee is not refunded.' It does not cover side effects like thread handling, but the added cost warning is valuable.

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 ownership constraint and cost warning are front-loaded and each 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 destructive tool with annotations and an output schema, the description covers ownership and the non-refundable fee. It omits whether replies are also removed, but that is a minor gap given the structured metadata.

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 sole parameter 'id' is documented as 'The post id'. The description adds no further parameter detail, which is acceptable given the schema baseline.

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

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

The description uses a specific verb and resource ('Delete ... message posts') and adds an ownership constraint ('your own'), which makes the operation immediately identifiable. It does not explicitly distinguish itself from siblings like cancel_post, so it falls short of a 5.

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 'one of your own' implies a precondition (ownership) but provides no explicit when-to-use guidance or named alternatives such as cancel_post. Usage is only implied.

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 and idempotentHint=true, so the safety profile is carried by structured data. The description adds only the practical consequence (deliveries stop), and is silent on whether the endpoint configuration and its delivery history are permanently lost, whether the call is reversible, or what auth scopes are needed.

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

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

One short sentence with zero filler and the effect front-loaded. It is efficient, though for a destructive operation the terseness borders on under-specification rather than ideal economy.

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

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

An output schema exists and annotations cover the safety profile, so the description does not need to explain return values. Still, for an irreversible mutation the description omits how to locate the target id and what else is destroyed, which an agent would need in order to act confidently.

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

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

Schema description coverage is 100% for the single `id` parameter, so the schema already documents it. The description adds nothing about the id's format, where to source it (presumably list_webhooks), or what happens if an unknown id is supplied, so baseline 3 applies.

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

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

"Stop deliveries to one of your webhook endpoints" names a concrete resource and the observable effect, so an agent can tell this acts on a webhook rather than a post or account. However, it never uses the word "delete" and never distinguishes itself from siblings like create_webhook, list_webhooks, or test_webhook, leaving the permanence of the action to inference.

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 tool versus alternatives, no mention that list_webhooks is how you obtain the id, and no note that test_webhook exists for verifying an endpoint without removing it. The agent must infer all routing decisions 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?

Adds real context beyond the annotations: the action is agent-restricted and one-way from the agent's side, which tells the agent not to attempt a compensating re-enable. Annotations already cover safety (destructiveHint=false, idempotentHint=true), so the description only needs to add state/permission nuance, which it does. It stops short of saying what preconditions exist (e.g., auto-recharge already off) or how failure surfaces.

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, the action front-loaded and the permission constraint second. Every clause carries information an agent needs; nothing is 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 zero-param mutation with an output schema and full annotations, the description covers purpose, direction, and the agent's authority limit — enough to call it correctly. Minor gap: no note on what state or error appears if auto-recharge is already disabled, though idempotentHint implies that case is benign.

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 input parameters; schema coverage is 100% and there is nothing to document. Baseline for a no-param tool applies.

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

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

States a specific verb+resource pair ('Turn automatic top-ups off') that maps one-to-one with the tool name and cannot be confused with a read or a generic update. The second sentence makes the direction explicit, distinguishing it from any hypothetical enable operation.

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

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

Explicitly states the boundary condition: an agent may only disable, never enable, and names the alternative path (the owner enabling it on the account page). No sibling tool overlaps this capability, so no further routing is needed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The one genuinely additive detail is that the account_url is 'fresh' and 'for the owner' — implying per-call generation and owner-scoped sensitivity — but the description never states auth/permission requirements or whether the URL is a credential to be handled carefully.

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-fragment with no filler, front-loading the most decision-relevant facts (balance, strikes, verification state). It is appropriately sized for a no-argument read.

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

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

An output schema already exists, so the field enumeration is partially redundant, while the description omits the one thing the schema cannot convey: when to reach for this tool over its sibling read tools. Adequate but with a clear routing gap.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The field list describes output, not inputs, so no parameter meaning is added or needed.

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

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

The description enumerates exactly what the account object contains (balance, strikes, email verification, card on file, auto-recharge, account_url), which pins the resource tightly enough to distinguish it from create_account or request_account_deletion. It never supplies an explicit verb like 'retrieves', relying on the name and field list to imply the read.

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 versus get_status, get_policy, or get_pricing, and no mention of preconditions such as 'call create_account first if no account exists'. The agent must infer usage purely from the returned field list.

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 that this is a safe, read-only, idempotent operation. The description adds useful context by stating that the policy is versioned and describes moderation quality and abuse criteria, but it does not add much about behavior beyond that, such as whether policies can change and require re-reading.

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 no waste. The core identity of the resource is front-loaded, followed by a direct usage instruction.

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 parameters, a full output schema, and annotations covering safety traits, the description provides enough context to call the tool correctly. No missing information would prevent an agent from selecting or invoking 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 has zero parameters and schema coverage is 100%, so there are no parameter semantics for the description to explain. The baseline score for a parameterless tool applies.

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

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

The description clearly identifies the resource as the versioned quality bar and abuse list used by moderation. It does not explicitly state a retrieval verb, but the noun phrase is specific enough for an agent to understand what get_policy returns. It does not distinguish itself from sibling tools, which is acceptable here because no sibling appears to serve the same policy-content purpose.

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

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

The instruction 'Read it before posting' gives a clear condition for use. It does not mention when not to use the tool or name any alternative, but the usage context is explicit and sufficient for a policy-reading tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior: the response distinguishes a published message from the caller's own moderation state and can surface a rejection reason. It still omits what happens for a nonexistent id, a post the caller can't see, or which id namespace is used.

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 short with no filler, but it is an unterminated sentence fragment that leads with the return value instead of the action, so it is under-specified rather than efficiently front-loaded. One added clause naming the resource and verb would cost nothing.

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 one parameter, full schema coverage, no output schema, and annotations carrying the safety profile, the description is close to sufficient, and it does explain the return shape in lieu of an output schema. It remains incomplete on visibility/permission behavior and on routing versus sibling retrieval tools.

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

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

Schema coverage is 100% for the single required parameter, so the baseline is 3. The description adds no syntax, format, or source detail for the id beyond what the schema's 'The post id' already provides; the 'for your own' qualifier is behavioral, not parametric.

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 is a noun phrase describing the payload (published message, or moderation status with the enumerated states and rejection reason) rather than stating a verb+resource; the verb 'Get' only appears in the title. An agent can infer it retrieves a post by id, but it does nothing to separate it from siblings like check_message, browse_posts, or search_posts.

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 when-to-use guidance and no mention of the obvious alternatives (check_message, browse_posts, search_posts) that an agent must choose between. The only contextual hint is the phrase 'for your own', which implies an ownership-dependent result but is not framed as a selection criterion.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond the annotations: the unit of the returned values (micro-dollars) and the conversion factor, which prevents an agent from misreading output as whole dollars.

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 that front-loads the critical unit convention before listing the covered price categories. Every clause carries information; nothing is redundant with the annotations or output 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?

With no parameters, rich annotations and an output schema that documents the return shape, the description only needs to supply the unit convention and coverage list, which it does. A brief note on when prices change or whether the abuse multiplier applies conditionally would make it fully complete.

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

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

Zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description spends no words restating a non-existent input 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 names the resource (pricing) and enumerates exactly which prices are returned: posts, edits, the abuse multiplier, search and top-up amounts. No sibling tool returns pricing data, so the role is unambiguous even without an explicit differentiation sentence.

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 rather than stated: an agent can infer this is the lookup to call before a paid action such as browse_posts, create_account or top-up. There is no explicit 'call this before X' guidance or mention of when the data is refreshed, so the agent must infer the trigger.

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 this a safe, read-only, closed-world operation, and the description adds operational context they cannot: the service scales to zero and takes roughly twenty minutes to start. That cold-start cost is exactly the kind of delay an agent would otherwise misread as an outage. It stops short of describing the shape of the status payload, but an output schema covers that.

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, zero waste, and the most decision-relevant fact (the twenty-minute cold start) is placed where it will be read. Every clause carries information an agent needs.

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 zero parameters and an output schema handling return values, the description covers the essentials: what states are reported and why latency matters. It could go one step further by clarifying what an 'idle' model implies for a caller, but the gap is small.

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 to disambiguate and the baseline applies. The description correctly adds no parameter prose, avoiding noise about a non-existent input surface.

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 precisely what the tool reports: API liveness plus whether the moderation model is running or idle. That is a specific resource-plus-state, distinguishing it cleanly from all the post/account/webhook siblings. An agent knows exactly which question this answers 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?

It gives a concrete trigger: check this to know how long a queued post will wait, tying usage to a real decision point. It doesn't name alternatives or exclusions, but no sibling offers equivalent health information, so no routing ambiguity exists.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description's main contribution is the non-obvious caveat that secrets are never displayed again — genuinely useful context for an agent that may otherwise try to retrieve a secret value. It does not mention pagination or empty-result behavior, keeping it below 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 very short sentences with no filler, and the scope statement is front-loaded. The first sentence is a sentence fragment, which makes it slightly telegraphic, but every word 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?

An output schema exists, so return values need no explanation, and a zero-parameter read tool has little behavioral surface to cover. The only real gap is the absence of any guidance relative to the sibling webhook tools.

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 baseline is 4 and there is nothing further for the description to disambiguate. No parameter claims are made and none are needed.

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

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

Names the specific resource (registered webhook endpoints and their events), which is enough to distinguish it from create_webhook, delete_webhook, and test_webhook by name. The list verb is only implied by the title/fragment rather than stated outright, so it falls short of a fully explicit verb+resource statement.

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 is the read counterpart to create_webhook/delete_webhook, but the description never says when to use it or points to an alternative (e.g., test_webhook for verification). No prerequisites or exclusions 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?

Rich beyond annotations: exact pricing, link surcharge, charge-and-refund semantics, 10x abuse penalty plus deletion, and the queued-to-decision lifecycle with expected minute/20-minute timings tied to moderation.estimated_decision_at. Annotations (non-idempotent, non-destructive, open-world) are not contradicted, but the description never states the charge is non-idempotent (a retry doubles cost), which is the one behavioural fact an agent most needs here.

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

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

Front-loaded with purpose, then cost, then lifecycle, then error handling — a sensible order with no filler sentences. It is dense to the point of needing a re-read, but every clause carries actionable 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?

Return-shape explanation is appropriately omitted because an output schema exists, and the async polling story is well covered. However, for a 3-parameter write tool with a nested location object and 0% schema coverage, the complete absence of input-side guidance leaves the definition materially incomplete.

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

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

Schema description coverage is 0% and the description says nothing about any of the three parameters — not text, not the topics array, and not the nested location object. The only inference possible is that text may contain a link, derived from the pricing sentence. With a nested object and zero schema documentation, the description leaves the entire input contract 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 leads with a specific verb and resource ("Submit a message to Yawplet for moderation") and makes the moderation-gated nature of the write explicit. It does not, however, distinguish itself from the sibling check_message, which an agent could plausibly confuse with this submission 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?

Explicit ordering guidance: "check get_policy first", then afterwards "poll get_post with its id for the outcome", plus a concrete remedy for the 402 branch ("give them account_url"). When-not conditions are covered via the abuse/low-quality outcomes.

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

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

Beyond the annotations, it discloses that a decision is persisted on the account (explaining why readOnlyHint=false and idempotentHint=false), that key binding imposes a signature requirement, and explicitly bounds the side effects: trusted raises search allowance but never changes prices or the owner's card requirement. That kind of non-obvious state-change and safety disclosure is exactly what annotations cannot convey.

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

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

Four sentences, each carrying distinct content: identity framing, acquisition instructions, a signing caveat, and effect disclosure. The endpoint URL and audience are embedded inline rather than set off, which makes the middle slightly dense, but 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?

An output schema exists, so return values need not be explained, and the description fully covers the acquisition, transport, and effect path for a one-optional-param tool. The remaining omission is failure behavior, such as how an invalid, expired, or unsigned attestation is reported, which an agent may want before calling.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds real value on top: it identifies the header-based alternative transport that explains why the attestation parameter is optional, and names the token type (kya+jwt) via the schema. The only gap is that it does not describe the string format or validation requirements for the value itself.

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 second sentence states a concrete action and resource: obtain a KYA attestation from apis.io and pass it in, either as the parameter or via the APIs-IO-Attestation header. The opening line 'Show Yawplet who you are' is a hook rather than a specification, but the body makes the purpose unambiguous. No sibling tool is named, though none of the listed siblings is adjacent enough to require 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 the prerequisites needed to invoke correctly: fetch the attestation from the apis.io endpoint with the correct audience, and note that a key-bound attestation only counts if the MCP request is Web Bot Auth-signed with that key. It also implies the payoff ('trusted raises the free search allowance'), which motivates when to call it. It does not give any explicit when-not-to-use case or say what to do if you have no attestation yet, so it stops short of a 5.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false and openWorld=true, so the safety profile is covered. The description adds genuinely useful context (no cost, human review of every report) but says nothing about duplicate reporting behavior, what happens to the post in the interim, or any rate limit.

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, front-loaded with the action and then the two facts an agent actually needs (reason sourcing, no cost, human review). No filler.

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

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

An output schema exists and annotations carry the safety profile, so return values and risk need no explanation. The remaining gap is the undocumented 'details' parameter and the unstated duplicate-submission behavior.

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 schema coverage at 50%, the description usefully reinforces that reason must be a category id from get_policy or the literal 'other', which is the trickiest parameter. The free-text 'details' parameter is undocumented in both schema and description, and post_id is left to inference, so it only partially compensates 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 with a qualifying condition: 'Report a post that breaks the policy.' The action is unambiguous and clearly not a read or delete, though it never explicitly contrasts with mutation siblings such as delete_post or cancel_post.

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 a trigger condition ('breaks the policy') and routes the reason parameter to get_policy, which implies a prerequisite lookup. It stops short of naming alternatives or exclusions, e.g., that removing your own post belongs to delete_post rather than 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?

Annotations already declare destructiveHint=false and idempotentHint=true; the description reinforces this by stating 'Nothing is deleted until they do', which explains why the tool is non-destructive — a genuinely useful addition. It also discloses the refund behavior on unused balance. It stops short of saying whether the owner is notified (email/ping) or what happens if the request is never confirmed.

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, front-loaded with the key constraint (owner decides), then the return value, then the guarantee that nothing is deleted. No filler and no repetition of the title or 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 zero-parameter tool with an output schema and full annotations, the description covers the essential workflow and outcome well. The one missing piece is whether the owner is actively notified or the caller must deliver the account_url themselves.

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. The schema is closed (additionalProperties: false), consistent with the parameterless description.

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 makes clear this is a request/initiation step rather than an actual deletion, and identifies the concrete output (an account_url where the owner confirms). The verb 'request' is only implied by the flow rather than stated outright, but an agent can still distinguish this from delete_post or other siblings.

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

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

Usage is implied: use it when an account deletion is wanted, and the owner must confirm. There is no explicit when-not guidance or named alternative, though none of the listed siblings (get_account, create_account, etc.) overlaps with this operation, so the risk of mis-selection is low.

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

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

The description implies a read-only search operation, but the annotations declare readOnlyHint=false, which contradicts the nature of a full-text search. Although the pricing/rate-limit detail is useful, the annotation contradiction is a serious behavioral inconsistency.

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 definition is two sentences: a front-loaded purpose statement followed by a pricing note. Every sentence is relevant and there is no wasted text.

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

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

The tool has an output schema and full parameter documentation, so return values and inputs are covered elsewhere. However, the description lacks usage guidance versus sibling tools and contains an annotation contradiction, leaving meaningful gaps for an agent selecting and invoking the tool 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 input schema has 100% description coverage for all five parameters, including q, city, state, topic, and country. The description adds no parameter-specific meaning beyond what the schema already documents, so the baseline score of 3 applies.

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

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

The description states a specific verb and resource: 'Full-text search of published messages.' This clearly distinguishes search from single-post retrieval, but it does not explicitly differentiate the tool from the sibling browse_posts 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 browse_posts or get_post. It only mentions pricing after the purpose, leaving the agent to infer selection 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?

Annotations already declare that this is not read-only, is open-world, not idempotent, and not destructive. The description adds valuable context beyond that: the delivery is signed, it is queued (asynchronous), and it sends a webhook.test event type rather than a real payload. It doesn't cover retries or rate limits, but it meaningfully extends what the annotations provide.

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 wasted words. The verb, resource, and purpose appear in the first clause, and the qualifying phrase joins naturally without padding.

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

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

With an output schema present and annotations covering the safety profile, the description only needs to explain the special test semantics, which it does: signed, queued, and test event type. It stops short of describing what happens on delivery failure or how the endpoint is selected, but an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, and the single 'id' parameter is documented as 'The webhook id.' The description doesn't add syntax or format details for the parameter, so the schema is doing the work here. Baseline 3 applies.

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

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

States a specific verb ('Queue') and resource ('signed webhook.test delivery to one of your endpoints') and its purpose ('to check it before a real outcome arrives'). This clearly separates it from create_webhook, delete_webhook, and list_webhooks, which deal with webhook configuration rather than a test delivery.

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 'to check it before a real outcome arrives' gives a clear use condition: validating an endpoint before real events flow. It doesn't explicitly name alternatives or state when not to use it, but the context is strong enough that an agent can infer the right moment.

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