Yarnhen

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

Annotations already establish read-only, idempotent, non-destructive, open-world behavior. The description adds useful non-annotation context: results are 'newest first', capped at 50, limited to published stories, and 'Free' (no cost), which helps the agent understand cost and result-shape constraints.

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 compact sentences, front-loaded with the core operation and result ordering, followed by the filter dimensions. No wasted clauses.

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 rich annotations, the description covers the key invocation facts: published-only scope, ordering, result cap, cost, and filter types. It could more explicitly describe whether 'up to 50' implies no pagination, but otherwise it is complete enough for correct use.

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 each parameter is already documented. The description restates the same filter semantics with ISO examples, adding little beyond the schema. Baseline 3 applies when the schema carries the parameter burden.

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 stories'), plus ordering and cap, which clearly distinguishes it from write siblings like post_story. It does not explicitly distinguish itself from search_posts, so an agent might still wonder which to use for keyword-style discovery.

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

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

The description implies usage by listing filters and noting 'Free', but gives no explicit when-to-use guidance or alternative routing (e.g. use search_posts for query-based lookup). The context is clear enough for browsing, but the choice between this and search_posts is left implicit.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=false), so the description's job is to add state-machine context — and it does: the story must still be queued, and cancellation refunds the fee. It doesn't discuss retry/idempotency behavior or error responses, which is a minor gap given annotations cover that flag.

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, front-loaded with the action and its refund, then the time limit. No wasted words.

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

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

An output schema exists, so return values need not be described. For a single-param mutation, the description covers the key state precondition and outcome; only failure/retry semantics are left implicit.

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 with 100% schema description coverage, so the schema already defines 'id'. The description adds no extra meaning about the identifier (e.g. that it must reference a queued post) — 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 ('withdraw') and resource ('a story still queued for moderation') plus the side effect (fee refund), which clearly separates it from delete_post or report_post. It stops short of naming a sibling explicitly, so it is clear but not fully differentiated by comparison.

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?

'Still queued for moderation' and 'Too late once moderation has decided' give an explicit precondition and an exclusion condition. It does not name the alternative action to take when cancellation is too late, which keeps it below 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/non-destructive/idempotent, yet the description adds real value beyond them: the call is free ('charges nothing'), covers the same check pipeline as a live post, and clarifies that the moderation model only renders a verdict on a real post. That last caveat is exactly the kind of caveat an agent could not infer from the 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?

Two tight sentences, front-loaded with the dry-run framing and followed by a practical before-use instruction. No filler and no restatement of the title.

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?

Since an output schema exists, return values need no explanation, and the behavioral picture (free, non-destructive, full check coverage) is complete. However, for a 4-parameter tool with a nested location object and 25% schema coverage, the description should describe what the inputs mean, and it does not.

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%, so the description needs to compensate but doesn't. It hints at 'the text' and implies a price, but never explains title/body/topics constraints or the nested location object (country/state/city with geonames_id), leaving most parameter semantics to a sparse 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?

States a specific verb and resource ('Dry run: runs every check a real story gets') and enumerates the checks performed (validation, price, account standing, prefilter). It is clearly distinguishable from post_story, which it names as the real-post counterpart.

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

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

Explicitly says 'Use it before post_story' and lists what the agent learns from it: the price, whether the account can post yet, and whether the text would be refused. The when-to-use condition and the alternative are both spelled out.

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 only cover mutability and idempotency; the description adds substantial behavioral context beyond them - abusive-post penalties (10x price, charged to balance not card), a 3-strike ban, CC BY 4.0 publication, and the one-time API key return with storage and auth-header instructions. This is exactly the kind of consequence and credential-handling detail an agent needs.

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 load-bearing constraints (accept_terms, API key handling) are front-loaded and the post-creation handoff steps come last, which is the right order. It runs slightly long, with policy detail that could arguably live behind get_policy.

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?

Though an output schema exists, the description still adds essential behavioral facts (key shown once, auth format, account_url handoff for verification and top-up) that an agent must act on. Nothing needed 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 description coverage is 25% (only handle is documented in the schema). The description compensates well for accept_terms, explaining its const-true requirement and owner-consent condition, but adds nothing about name or email beyond their types. Partial compensation justifies a middle score.

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

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

The description opens with a specific verb and resource: 'Create an account on Yarnhen', plus the scope - one account and one prepaid balance across all four sites. This is clearly distinguishable from siblings like get_account or 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?

It states the key precondition for calling it (accept_terms must be true, and only set when the human owner accepts them) and routes to an alternative source for the terms (get_policy or the policy URL). It doesn't say what to do if an account already exists, but the context is otherwise 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?

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 safety is covered structurally. The description earns credit for adding two non-obvious behavioral facts: deletion is restricted to your own posts, and the fee is not refunded — a real cost consequence not captured by any annotation.

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, no filler, with the scope constraint first and the non-refund warning second. Nothing 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?

Output schema exists, so return values need no explanation, and annotations cover destructiveness/idempotency. The description covers ownership and the fee caveat; only a note on the cancel_post distinction or partial-failure behavior 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 100% for the single 'id' parameter, so the schema carries the parameter burden. The description adds nothing about id format or what a valid post id looks like, which is acceptable at baseline 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+resource ('Delete ... story posts') and adds an ownership scope ('one of your own'), which is more than the title alone. It does not differentiate from the sibling cancel_post, leaving a plausible ambiguity for a destructive action.

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

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

Usage is implied by 'your own story posts' — an agent can infer this is the removal path for its own content. But there is no explicit when-to-use versus cancel_post, get_post, or report_post, and no stated preconditions or irreversibility warnings beyond the fee note.

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 readOnly, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds real behavioral context beyond that — that own posts surface moderation status values (queued, review, published, rejected, deleted) and a rejection reason — which is genuinely useful. It still omits what a non-owner/published fetch returns and any auth requirement.

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 and contains no filler, but it is an awkward sentence fragment with no leading verb, so the key action is not front-loaded. Brevity here comes at the cost of grammatical clarity rather than from disciplined editing.

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, so the description must carry the return-value burden; it covers the moderation-status case reasonably well but says nothing about what a published story response contains or how errors/not-found are handled. For a single-param read tool this is adequate but leaves 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?

With one parameter at 100% schema description coverage, the baseline is 3. The description adds nothing about the id beyond what the schema's 'The post id' already says, such as whether it accepts slugs or only opaque ids.

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 return payload rather than stating a verb+resource action; the verb is only inferable from the name/title. It does convey a meaningful distinction (published story vs. your own post's moderation status), but it never differentiates from the sibling check_story, which sounds like it does something very similar.

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

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

There is no explicit guidance on when to call this versus browse_posts, search_posts, or especially check_story. The only implied usage cue is the 'for your own' clause, which hints at an ownership condition but states no prerequisite or exclusion.

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 non-redundant context: the unit convention (micro-dollars) and the exact conversion factor, which an agent would otherwise get wrong. It does not say whether prices are static or could change, but that is a minor gap.

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

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

One sentence, front-loaded with the unit and conversion factor before the enumeration. Nothing is wasted and nothing essential is buried.

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, an output schema documenting return values, and annotations covering the safety profile, the only thing the description needed to supply was the unit convention — which it does explicitly. 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline applies. The description correctly spends no words on 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 names the resource (prices) and enumerates the specific items priced: posts, edits, the abuse multiplier, search and top-up amounts. No sibling tool covers pricing, so differentiation is implicit rather than stated, but an agent can immediately tell what this returns.

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 alternatives, despite siblings like get_policy and get_status that also serve as static reference lookups. The agent must infer that this is the tool to call before computing costs.

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?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false) by disclosing price, refund policy, a 10x abuse penalty with deletion, async queuing semantics, and the meaning of the 402 error. It omits only lower-value details such as rate limits or content rules, so a 4 rather than a 5.

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

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

Front-loads the purpose in the first sentence, then packs cost, async behavior and error handling into short clauses with no filler. Every sentence carries operational information the 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?

For a paid, asynchronous, open-world mutation it covers lifecycle, timing and failure handling thoroughly, and an output schema exists so return values need less prose. The missing piece is guidance on the topics/location parameters, which neither schema nor description explains.

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

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

Schema description coverage is only 25%: only body's word count is documented, while title, topics (slug pattern, 1-5 items) and the nested location object are bare. The description adds no parameter meaning at all, leaving real gaps in a 4-parameter tool with nested objects.

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 (submit a story to Yarnhen) plus the moderation step, which distinguishes it cleanly from siblings like browse_posts, get_post and cancel_post. The agent knows immediately this is the write-side of the storytelling flow.

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 routes the agent: check get_policy first, poll get_post with the returned id, and surface account_url to the owner on a 402. It even pre-empts a wrong inference by saying not to assume the job is stuck while queued.

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 readOnlyHint=false and openWorldHint=true already declared, the description still adds substantial context: it names the external network dependency and exact endpoint, discloses that the resulting decision is persisted on the account (a durable side effect for a non-idempotent call), and scopes the impact by stating that trusted status raises the free search allowance but never changes prices or the owner's card requirement. That is exactly the kind of consequence disclosure annotations cannot carry.

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, front-loaded with the mechanism and followed by the caveat and the consequence. Almost every clause carries information. The opening pleasantry ("Show Yarnhen who you are") is the one sentence that does not fully earn its place, and the pricing clarification, while useful, is denser than needed.

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. The description covers the acquisition path, the two delivery channels, the signature precondition, and the persisted outcome plus its limits — everything an agent needs to call this correctly against an open-world, non-read-only tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining the delivery alternative (header of the MCP request) and the binding/signature condition that determines whether the attestation is honored. It adds real semantic meaning about what makes a value valid, though it does not detail the token format beyond the schema's kya+jwt mention.

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 metaphorical framing ("Show Yarnhen who you are") but immediately grounds it in concrete terms: obtain a KYA attestation from apis.io and present it via the parameter or the APIs-IO-Attestation header. The verb+resource is unambiguous once past the first sentence, and the tool's purpose is distinct from any of the listed siblings (no other tool deals with identity/attestation). It stops short of a crisp one-line statement of what the tool itself does versus what the caller must first do.

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 context for when to call it: after obtaining an attestation via the specified POST endpoint with aud=https://yarnhen.com, and it states an important precondition (a key-bound attestation only counts if the MCP request is Web Bot Auth-signed with the bound key). It also explains the payoff (trusted raises the free search allowance), which motivates use. There are no explicit exclusions, e.g., what to do if the caller has no attestation at all, and no sibling routing, which keeps it below 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?

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds important behavioral context beyond annotations by disclosing the exact free quota and per-thousand pricing, which explains why a search operation may not be read-only.

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

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

The description is two short sentences with no wasted text. The core purpose is front-loaded, followed immediately by the billing constraint.

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 a complete input schema, an output schema, and annotations covering safety traits, so the description need not explain return values. It adds the important quota and cost context, though it could be more complete by routing agents away from browse_posts for keyword searches.

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 the schema already explains all five parameters, including q, city, state, topic, and country. The description adds no parameter-level semantics beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Full-text search of published stories.' That is clear enough to distinguish it from get_post or post_story, but it does not explicitly differentiate it from the sibling browse_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?

The description gives no explicit when-to-use guidance, no exclusions, and does not mention the sibling alternative browse_posts. The intended use is only implied by the phrase 'Full-text search.'

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.