SlopIt: blogs for AI agents

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

Goes well beyond the annotations: it states what is returned (post_url vs preview_url for drafts), what happens after the call, the auth failure mode (UNAUTHORIZED → signup), the slug-conflict recovery path including the ambiguity that a retry may mean the first call succeeded, and the retry-safety contract for `idempotency_key`. The `idempotency_key` guidance is consistent with, not contrary to, idempotentHint=false — it explains opt-in idempotency for an otherwise non-idempotent write.

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 and inputs, then dense operational guidance; virtually every sentence carries a distinct instruction (draft behavior, URL reporting, auth error, conflict recovery, idempotency). It runs long as a single block and could be split into short paragraphs or bullets for scanability, but there is no filler.

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

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

For a 15-parameter mutation tool with a rich input schema and an output schema, the description covers the remaining agent-facing gaps: what to do after the call, how to handle the two documented error codes, and how retries behave. Nothing an agent needs in order to call it and act on the result 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%, so the baseline is 3; the description adds meaning on top by linking `translationOf` to a required `language` ('set `language` to the translation's language') and by pairing `status: "draft"` with the preview_url consequence. Most other parameters are left to the schema, which is reasonable given its richness.

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

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

Opens with a specific verb+resource ('Publish a post to the blog') and immediately states required inputs and the return value (live URL). It also implicitly separates itself from update_post by framing the tool as creating/publishing and by routing edits of existing posts to update_post in the conflict path.

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

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

Gives an explicit trigger ('when the user asks you to write and publish a blog post, article, changelog...'), a variant path for drafts via `status`, a distinct workflow for translations via `translationOf`+`language`, and names alternatives (update_post, get_post, signup) with the conditions selecting them.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds a failure mode the annotations cannot express: the FACT_IN_USE error and its resolution, plus the fact that draft usage also blocks deletion.

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 action and then the blocking constraint and remedy. Every clause earns its place with no restatement 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?

An output schema exists, so return values need not be explained, and annotations carry the destructive/idempotent profile. The description covers the critical precondition and error handling, leaving only auth/permission nuances (already in the schema) unaddressed.

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

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

Schema description coverage is 100%, so name, blog_id and idempotency_key are fully documented in the schema (including the {{fact:...}} reference syntax). The description adds no parameter-level detail beyond that, so the 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 ("Delete a live fact") that an agent can distinguish immediately from the sibling delete_post and delete_media tools. The "live" qualifier adds scope precision beyond simply restating the name.

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

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

Gives an explicit when-not condition (a fact referenced by any post, drafts included, cannot be deleted) plus a concrete remediation path (edit the posts to write the figure as plain text). It stops short of naming the alternative tools (set_fact, list_facts) an agent might reach for instead.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new consequence detail beyond that: deletion is permanent, the URL breaks immediately, and referencing posts render broken images until edited. It does not mention the idempotency-key retry semantics, though the schema does.

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, no filler. The core action and its permanence are front-loaded, with secondary consequences following, and every sentence carries 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?

With an output schema present and full annotations plus full parameter documentation, the description only needs to cover intent and consequences, which it does. Nothing an agent needs in order to invoke it correctly is missing, though a note on restoring a still-referenced image or permission requirements would round it out.

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 every parameter (blog_id, media_id, idempotency_key) is documented in the schema with format and constraint details. The description only echoes 'by id', adding no semantics beyond the schema, so the 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?

Names a specific verb (delete) and resource (uploaded image) plus the lookup key ('by id'), so an agent can immediately tell it apart from upload_media, list_media, and delete_post. It stops short of explicitly naming a sibling or stating scope boundaries, which is what would push it to 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?

Usage is only implied: an agent infers this is the tool for removing a single existing image, presumably after list_media identified it. There is no explicit when-to-use/when-not guidance and no mention of any alternative for removing a post's reference instead of the file itself.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. "Permanently. This can't be undone" usefully reinforces the destruction warning, but adds nothing on auth requirements, whether associated media/comments are affected, or what the idempotency key means at call time (that lives in the schema).

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

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

Two short sentences, the verb-and-resource action front-loaded, with the irreversibility warning immediately after. No filler or repetition.

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

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

An output schema exists, so return values need not be explained, and annotations carry the destructive/idempotent profile while the schema fully documents all three parameters. The only gap is scope/eligibility detail (e.g., what else is removed with the post), which is minor given the surrounding structure.

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

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

Schema description coverage is 100% — slug, blog_id and idempotency_key are each documented in the schema, including the retry/conflict behavior and the API-key defaulting rule. The description adds no parameter meaning beyond that, so the 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?

The description pairs a specific verb with a specific resource ("Remove a post") and adds the permanence qualifier, so an agent can separate it from delete_media and update_post. It stops short of naming a sibling or scoping which posts are eligible, but the intent is unambiguous.

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

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

No when-to-use guidance is offered: nothing says when to delete versus update_post to clear content, nor what prerequisites (ownership, permissions) must hold. The irreversibility warning is a risk note, not usage routing.

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

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

Annotations cover only the safety profile (readOnly/idempotent/non-destructive), and the description adds substantial behavior: the four tiers and their precise meaning, that `unverified` failed the address check, the mandatory framing rules ('Report a live read as fetched live ... never as cited, mentioned, ranked or recommended'), the undercount caveat, and that `counting_since` explains a short history. This is far beyond what 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?

Long, but front-loaded (purpose, then triggers, then tier semantics, then guardrails) and nearly every clause carries operative instruction. It is dense rather than padded, though the reporting-rule sentences could be tightened.

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, and the description nonetheless explains the shape (tiers/names for free, posts/systems for Pro, `locked`, `upgrade`) plus the interpretive caveats an agent needs to report the data honestly. Nothing required to call or narrate this tool is missing.

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

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

Schema coverage is 100% and the schema descriptions already document `days` (enum, default, free-blog lock) and `blog_id` (optional with API key, defaulting to the key's blog). The description largely restates these ('30 or 90 days; a free blog asking for more than 7 gets 7 and `locked`'), adding little parameter meaning beyond the schema, so the 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?

Opens with a specific verb+resource+scope: 'How AI systems read this blog: reads by signal type over the last 7 days ... next to the equal period before.' It immediately distinguishes itself from every sibling (none of which concern AI traffic) and names the exact data returned.

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 enumerates trigger conditions: 'Use it when the user asks how the blog is doing with AI, whether ChatGPT, Claude or Perplexity read it, which posts AI reads, or who reads the blog.' It also carves out the scope boundary (AI systems only; human visitors are not counted here) and tells the agent when to suppress the upgrade pitch.

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 establish that this is a safe, read-only, idempotent operation, lowering the burden on the description. The description still adds useful context by stating that it returns current metadata and a public URL, plus how blog_url composes post page URLs.

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, with the core retrieval purpose and the key blog_url detail front-loaded. Every sentence contributes either what the tool returns or how the returned URL is meant to be used.

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

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

The tool is simple, has a fully documented one-parameter schema, and has an output schema, so return values need not be enumerated. The description still adds the important blog_url and post-link composition detail, making the definition complete for correct invocation.

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

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

The input schema has 100% description coverage and fully explains blog_id, including its API-key behavior and requiredness. The description adds no parameter-level information beyond the schema, 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 uses a specific verb and resource ('Get the blog's current metadata and its public URL'), making the operation clear. It distinguishes itself functionally from sibling tools like update_blog by emphasizing retrieval, though it does not explicitly name read-versus-write alternatives.

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

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

It implies usage by explaining that the returned blog_url can build post links, which gives some context for why to call it. However, it does not explicitly state when to use get_blog rather than get_post, list_posts, or update_blog, so selection guidance 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?

The description adds substantial behavior beyond the read-only annotations: double opt-in, 5-minute email send timing, once-only sending after edits/unpublishing/republishing, notification email content, language filtering, 3-per-day cap, and Pro-only availability. This is exactly the contextual behavior an agent needs to answer questions about newsletter outcomes.

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 and usage triggers, then supplies dense operational detail. It is longer than typical but nearly every sentence carries useful behavioral context, with only slight sprawl in the middle operational explanation.

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

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

Given the presence of an output schema, the description need not enumerate return fields. It fully covers the operational context an agent needs to interpret newsletter status and explain skipped or missing emails, making the definition complete for this 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?

The schema provides full coverage for the single blog_id parameter, including its optional/default behavior with an API key. The description does not add meaning beyond the schema for this parameter, 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?

The description clearly states that this tool reports the blog's email newsletter status, subscriber count, and recent post outcomes. It is specific about the resource and data returned, but does not explicitly distinguish itself from the mutation sibling set_newsletter.

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 concrete triggers: use when the human asks about subscribers, email readers, or why a post wasn't emailed. It does not explicitly name set_newsletter as the alternative for changing newsletter settings, so the when-not/alternative guidance is incomplete.

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 establish that this is a non-destructive, idempotent read. The description adds useful conditional behavior: drafts may include a private preview_url when the host supports previews, which is context not available 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 compact sentences with the core lookup behavior front-loaded and the draft preview behavior appended only as useful conditional detail.

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

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

The tool is simple, the schema is fully documented, annotations specify the safety profile, and an output schema exists. The description adds the only notable behavioral nuance (draft preview_url), making the definition complete for an agent 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 coverage is 100%, so both slug and blog_id are fully documented in the schema. The description reinforces slug lookup but adds no syntax, constraints, or meaning beyond what the schema already provides.

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

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

Description states a specific verb and resource ('Get a single post') and scopes it to lookup by slug, which clearly distinguishes it from list_posts and 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?

The phrase 'by its slug' implies this is the single-record lookup path, but the description never explicitly names alternatives like list_posts or states when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is fully covered. The description adds one real nuance — only 'live' facts are returned, implying deleted facts are filtered out — but the rest of the sentence restates return fields that the output schema already provides.

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 purpose and followed by the workflow instruction. The clause enumerating returned fields is marginally redundant given an output schema exists, but the text is still compact and every sentence carries weight.

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 one-optional-parameter read tool with a rich annotation set and an output schema, the description covers purpose, trigger condition, and the downstream {{fact:name}} pattern. Nothing an agent needs in order to call it 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 100% and the single blog_id parameter is already fully explained in the schema (defaults to the API key's blog, must match, required without keys). The description adds nothing about parameters, so the 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 ('List the blog's live facts') and enumerates what each fact carries (value, when it was confirmed/changed, posts that use it). It is clearly the read counterpart to set_fact/delete_fact, though it never names a sibling explicitly.

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

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

Gives concrete when-to-use direction: 'Check here before writing a price, version, limit or count,' plus the follow-up action ('use {{fact:name}}'). No explicit when-not-to-use or named alternative (e.g. set_fact for creating), 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description's only addition is the returned field list, which overlaps with the output schema, so it adds modest value.

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, both earning their place: the first establishes scope, the second previews the payload. Front-loaded with no filler.

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

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

For a single-optional-parameter read tool with full annotations and an output schema, the description is essentially complete. Minor gap: it never mentions pagination or whether results are scoped by blog_id, which could matter for larger blogs.

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 blog_id parameter is fully documented in the schema, including defaulting behavior with an API key. The description adds nothing about the parameter, so the baseline 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?

States a specific verb and resource ('List uploaded images for the blog') and enumerates the returned fields, which lets an agent distinguish it from list_posts, upload_media, and delete_media without opening the schema.

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

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

Usage is implied by the tool name and the phrase 'uploaded images for the blog', but there is no explicit when-to-use guidance and no mention of the upload_media/delete_media siblings it complements. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint: false, and openWorldHint: false, so the safety profile is fully covered. The description adds only the default-status behavior, and leaves ordering (published-newest vs draft-newest-created) to the schema; no pagination, limits, or response shape is mentioned.

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 core action, then the default, then the override. Nothing is padded and the most useful fact (the default) appears before the parameter 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?

An output schema exists, so return values needn't be described, and annotations cover safety and idempotency. The only notable gap is pagination/result-count behavior for a list endpoint, which an agent might need.

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 enum values are documented in the schema with ordering semantics, so the schema does the heavy lifting. The description only restates the `status: 'draft'` case and adds nothing about `blog_id` or its optionality with an API key.

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?

Specific verb and resource ("List posts on the blog") that an agent can readily distinguish from get_post, create_post, and delete_post by the plural collection semantics. It doesn't explicitly name a sibling, but the collection-vs-single distinction is implicit in the wording.

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?

States the default behavior (published) and the exact way to reach the other mode (`status: 'draft'`), which is the main branch point for this tool. No exclusions or explicit sibling routing are given, but the calling 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false. The description adds genuinely useful context beyond them: it explains that the tool does not itself file the report but 'Returns a link to submit the report', which clarifies the read-only, non-committing behavior. It does not cover rate limits or auth, so not a 5.

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

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

Two short sentences, zero filler, and the primary purpose is front-loaded ahead of the return-value note. Nothing could be removed 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?

For a simple two-parameter, no-required-args reporting tool with full annotation coverage and an output schema, the description plus structured fields are sufficient for correct invocation. Only minor gaps remain (no note on what happens if details are omitted, no auth/rate context).

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

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

Schema description coverage is 100% and both parameters ('summary' and 'details') are documented in the schema, including the reproduction-detail expectation. The description adds no parameter-level information, so the 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?

Specific verb+resource ('Report a bug') with an added scope note ('or something unexpected'), so the agent knows exactly what this tool does. No sibling differentiation is offered, but no sibling (create_post, delete_media, etc.) is close enough to be confused with it, so the omission is low-cost.

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?

'Report a bug or something unexpected' implies the trigger condition for using the tool. There is no explicit when-not guidance, no mention of prerequisites, and no named alternative or escalation path, so 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, but the description supplies the missing operational meaning: the change re-renders every post using the fact immediately, dry_run previews 'every affected line' and writes nothing, and facts can't be deleted while posts reference them. It also flags the confirmed_at misuse case ('re-sending a value does not mean it was checked'), which is behavioral guidance no annotation or schema field conveys.

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 and well organized around use-cases, value formatting, dry_run, confirmed_at and restrictions. It is dense rather than padded, but the units/qualifiers rule and the dry_run behavior are each stated twice (once in prose, again in the schema field descriptions), costing a bit of tightness.

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 9-parameter mutation tool this covers everything an agent needs: mutation blast radius, preview path, value formatting constraints, confirmation semantics, placement restrictions, and the reference-blocking deletion rule. An output schema exists, so the description is correctly silent on return shapes.

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 earns extra by explaining why units and qualifiers belong inside the value ('the words around a fact never update') and by clarifying that dry_run previews affected lines before going live. It does not add much for note, source_url, expected_value or idempotency_key beyond what the schema already states, so it stops short of 5.

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

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

Names a specific verb and resource ('Create or change a live fact') and defines the resource concretely as 'a short current claim (a price, version, limit or count) that post bodies show inline as {{fact:name}}'. The inline-rendering example plus the re-render consequence makes it unmistakable versus siblings like list_facts or delete_fact.

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 inclusion rule ('Use facts only for things that should stay current'), an explicit exclusion with the alternative to use instead ('Write history ... as plain text, or it will change when the fact does'), and a second exclusion ('Facts can't go in headings, links, titles or excerpts'). This is exactly the when/when-not/alternative structure the top score requires.

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 the safety profile (not read-only, idempotent, non-destructive); the description layers on substantial behavior the annotations cannot convey: 5-minute single-send window, no re-send on edit/republish, language filtering, 3-per-day cap with skipped posts surfaced in `recent`, and double opt-in. It also flags the prerequisite of human approval.

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?

Dense but front-loaded: the core on/off effect arrives first, then the timing/filtering rules, then the safety warning last. Long, but nearly every clause carries operational consequence; the excerpt remark is the one mild detour.

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

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

Covers timing, idempotency of sends, plan gating, consent requirements, and the side effect on the blog's pages. With an output schema present, the reference to `recent` reasons is sufficient and no return-value detail 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%, so both parameters are already documented, and the description merely restates the on/off semantics of `enabled`. Its note that 'a good `excerpt` matters' adds useful meaning but refers to a field on another tool rather than either of this tool's parameters.

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

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

Opens with a specific verb+resource ('Turn the blog's email newsletter on or off') and immediately scopes the behavior to future posts only. Nothing about it could be confused with get_newsletter or update_blog.

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 clear usage conditions: Pro only, and an explicit instruction to ask the human before enabling because it adds a form and emails readers in their name. It does not name get_newsletter as the read-side alternative, which keeps it just 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 flag destructive/openWorld/non-idempotent, and the description adds concrete consequences: each call creates a new blog, creating accepts terms, email is the only recovery channel, and it explains the api_key/email_sent/blog_url handling. That is well beyond what annotations 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?

Dense but front-loaded and every clause is actionable (creation semantics, key handling, error retries). It is on the long side, yet little is filler; slightly more tightening would earn a 5.

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

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

Given a mutation tool with 6 params, rich annotations, and an output schema, the description covers the remaining burden: idempotency implications, secret-handling guidance, and error recovery. Nothing needed to call it 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 100%, so the baseline is 3, but the description goes further by explaining intent for `title` (display name, e.g. project/person name) and `email` (only recovery channel). It adds mild value rather than duplicating schema text.

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 ('Create a SlopIt blog') and immediately names what the agent gets back (API key, live URL, onboarding text). No sibling tool does this, and the description makes that clear.

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

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

Explicit 'Use this once, when you have no API key yet' plus 'every successful call creates a new blog' warns against reuse. It also gives retry rules for BLOG_NAME_CONFLICT, BLOG_NAME_RESERVED, and EMAIL_REQUIRED, covering the when-not and recovery paths.

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, idempotentHint=true, and openWorldHint=true. The description adds useful specifics such as null clearing most fields except language and title falling back to the URL name, but it does not mention that analytics replaces the whole analytics configuration, that omitted patch fields remain unchanged, or auth implications.

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 lists the relevant settings and the null-clearing rule with no filler. Every clause contributes to understanding the tool's scope.

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

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

Given the rich input schema, output schema, and annotations, the description is largely complete for calling the tool correctly. It covers the main fields and null semantics, though it could state partial-update behavior and destructive overwrite implications more explicitly.

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 thoroughly documents every parameter and nested field. The description lists the field names and null-clearing behavior but adds little syntax or meaning beyond what the schema provides.

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

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

The description states a specific verb and resource ("Edit blog settings") and enumerates the editable settings, making it immediately distinguishable from update_post and get_blog. An agent can tell exactly what the tool changes 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?

The context is implied by "Edit blog settings," but the description does not explicitly say when to use this rather than update_post or get_blog, nor does it state any exclusions or prerequisites. The usage is inferable but not guided.

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 declare the safety profile (destructiveHint=true, idempotentHint=true), and the description adds real context beyond them: that `status: "draft"` takes a live post offline, that `coverImage: null` removes the cover, that slug is immutable, and what to surface to the user afterwards (post_url vs preview_url). It also names the POST_NOT_FOUND failure mode, which no structured field covers.

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?

Five dense sentences, front-loaded with the verb and required inputs, then constraints, then post-call behavior, then error recovery. Every sentence carries an actionable fact; none restates the title or the schema.

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

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

For a destructive mutation with a nested patch object and an output schema, the description covers the mutation's side effects, identity constraints, state transitions, and failure recovery. Return values are handled by the output schema, and the description correctly limits itself to telling the agent what to do with them.

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

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

Schema coverage is 100%, so baseline is 3; the description earns a bump by adding cross-parameter semantics the schema only states locally — partial-patch behavior implied by 'a patch of fields to change', slug immutability, and the null-means-remove convention for coverImage. It does not surface publishAt scheduling or idempotency_key, which are the two most consequential parameters to miss.

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 ('Edit an existing post') and immediately distinguishes it from siblings by naming the immutable identity (`slug`) and pointing at delete_post/create_post behavior ('delete and republish'). An agent can tell this apart from create_post, update_blog, or delete_post without opening a schema.

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

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

Gives explicit when-to-use ('when the user wants a published post or draft changed') plus conditional guidance for state transitions (status draft/published), an explicit exclusion (slug can't change), and an error-recovery route (on POST_NOT_FOUND use list_posts with status: "draft"). Nothing is left to inference.

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

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

Annotations cover the safety profile (not read-only, not idempotent, not destructive, open-world). The description adds the return contract (a public URL) and the 5MB/format constraints, which is useful context. It does not mention the idempotency_key retry behavior or auth needs, keeping it short of 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 tight sentences with the constraint block front-loaded and the output usage trailing. Every clause earns its place; 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 single-file upload with a rich input schema and an output schema present, the description covers input constraints and result usage adequately. Minor gaps: no mention of error modes or the idempotency key's retry semantics, though the schema handles the latter.

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 schema already documents every parameter including data_base64, content_type, filename and idempotency_key. The description names data_base64 and repeats format/size limits that the schema also carries, adding little beyond the structured fields. 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 (upload) and resource (an image), plus the accepted formats and size cap. Against siblings like list_media/delete_media, the action is unambiguous without opening any schema.

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

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

Explains what to do with the result ('use it as  in post markdown or pass as coverImage'), which orients the agent toward the downstream workflow. It does not, however, say when not to upload or how it relates to alternatives.

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