polyblog

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

Beyond the annotations (destructive, non-idempotent, open-world), the description discloses real behavioral traits: it returns the created id and title, fires an `article.created` webhook (an external side effect not visible in annotations), defaults to unpublished, and only creates a public page when published. This adds meaningful context the annotations do not 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?

Three sentences, front-loaded with the core create behavior, then publishing semantics, then the translation nuance. Almost every clause earns its place; slightly dense but 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, so return values need not be re-explained, and the annotations cover the safety profile. The description handles the two genuinely tricky behaviors (publication default and translation grouping), with the remaining gap being the many undocumented optional parameters.

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 27% (3 of 11 params), so the description does useful work by deeply explaining `originalArticleId` (original vs sibling id), `locale`, and `published`. However, `slug`, `author`, `format`, `categories`, and `description` remain undocumented in both places, so it only partly 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?

The description states a specific verb and resource ("Create a new Polyblog article") plus a scope ("in the given blog"), and it distinguishes itself from sibling update_article/generate_article by emphasizing creation of a new article. An agent can identify the operation 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?

It gives clear conditional guidance: pass `published: true` to also publish, and pass `originalArticleId` + `locale` to create a translation rather than a separate article. It does not explicitly route the agent away from alternatives like generate_article or create_blog, so it stops short of full when-not/alternative coverage.

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, openWorldHint=true and idempotentHint=false; the description reinforces this by explaining that a name clash 'fails rather than being adjusted' (non-idempotent behavior) and by disclosing a side effect the annotations cannot express: a `blog.created` webhook fires to organization subscribers. It does not cover auth/permission requirements, but the added side-effect context is genuine value beyond the structured hints.

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 dense sentences with zero filler: identity/scope first, the consequential uniqueness rule second, the side effect third. Every sentence carries information an agent can act on.

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

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

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. The description closes the biggest functional gap (failure-on-name-clash and webhook emission), but omits permission requirements and validation constraints for the non-required parameters.

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 60%, with `name` already documented in the schema as the globally-unique subdomain and `locales`/`defaultLocale` partially documented, so the description largely repeats the schema on `name`. It adds nothing about locales, description or articlesFormat, leaving the uncovered tail of parameters undocumented in both places.

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 ('Create a new Polyblog blog') and scopes it to 'the signed-in organization', which is concrete and unambiguous. It stops short of naming or contrasting with siblings (e.g. create_article, get_blog), so an agent gets a clear purpose but no explicit routing signal.

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

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

Usage is implied by the name and description rather than stated: there is no explicit when-to-use, no prerequisites (e.g. org admin rights), and no mention of alternatives like get_blog or list_blogs. The one useful constraint given is that a clashing name fails rather than being auto-adjusted, which implicitly tells the caller to check name availability first.

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 flag destructiveHint and non-readOnly, but the description goes well beyond them: it states permanence, that it removes the public page, fires an article.deleted webhook, and is irreversible. That is exactly the side-effect and blast-radius context an agent needs, and it is consistent with 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?

Three short sentences, front-loaded with the action and resource, then consequences, then the safety instruction. 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 no explanation, and annotations cover the mutation profile. Combined with the disclosed irreversible side effects and webhook, an agent has everything required to call this destructive tool safely.

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 fully documented in the schema itself. The description adds no format, lookup, or validation detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource ('Permanently delete a Polyblog article by id'), with the scope-limiting 'by id' qualifier. The sibling list contains get_article, update_article, and create_article, and the 'Permanently delete' phrasing cleanly separates this from all of them.

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 clear precondition ('confirm with the user before calling') that an agent can act on, which is the relevant when-to-use trigger. It does not name a sibling alternative (e.g. update_article for soft edits), so it falls 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 destructiveHint=true, openWorldHint=true and non-idempotency, but the description adds traits the schema can't express: paid model usage, a 30–60 second latency expectation, and that cover/inline image generation is always disabled. The draft-by-default persistence behavior is also surfaced, though there is no mention of failure modes or whether an aborted run still consumes paid usage.

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

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

Three tight sentences with zero filler. The core output shape and constraints are front-loaded, and cost/latency comes last where it belongs as a caveat.

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

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

For a 7-parameter, open-world, paid, destructive generation tool with an output schema, the description covers cost, latency, persistence default, and the topic/topicIdeaId branch. It omits the mutual-exclusion edge case between topic and topicIdeaId and any note on partial-failure behavior, but the presence of an output schema removes the need to describe return values.

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 documents topic, blogId, locale, persist, autoPublish, topicIdeaId and sitemapMaxUrls in detail. The description adds a little context around sitemapMaxUrls (internal-link pool) and persist (dry-run preview) but largely restates what the schema provides; baseline 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?

States a specific verb+resource (generate a text-only SEO blog article) and adds real scope detail: LLM-drafted bounded HTML, internal links drawn from the blog customDomain sitemap.xml, saved as draft by default. It implicitly separates itself from the sibling create_article via 'generate an LLM draft', but never names or contrasts with that sibling explicitly, so differentiation is left 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?

It gives a genuine either/or input rule ('Pass `topic` or `topicIdeaId`'), which is useful routing. However it never says when to choose this tool over create_article, nor what happens if both or neither are supplied, so usage context is only partially 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 readOnlyHint and idempotentHint, so the description adds value by disclosing output behavior: allowlisted metadata, an 8,000-character content cap, and an explicit truncation flag. It could more clearly state that truncation may occur but does not explain whether pagination or full content retrieval is possible.

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 tightly written sentences front-load the core action and then immediately disclose the notable output constraints (cap and truncation flag). Every component 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 the description needn't detail return values, but it helpfully surfaces the 8,000-character cap and truncation flag that an agent should plan around. It falls slightly short of 5 because it omits any mention of authorization or error behavior when the article is not found.

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%: both parameters (idOrSlug and locale) are already documented. The description reinforces the id/slug dual-purpose semantics and the locale disambiguation role but adds little beyond the schema. Baseline 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?

States a specific verb (fetch), resource (Polyblog article), and the two lookup modes (by id or by slug+locale). Cleary distinguishes from siblings like search_articles and list_article_translations by emphasizing single-article retrieval.

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

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

The description implies when to use it (single article fetch by id or slug) but offers no explicit when-to-use vs alternatives such as search_articles or show_article_preview. Usage is inferable from the sibling set but not directly 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the return format (Markdown), which is useful, but discloses nothing about error behavior when the id/name is not found.

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 resource, then the return format. 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, so return values need not be explained; the description still notes the Markdown formatting. For a simple single-item read tool with full annotations and full schema coverage, this is nearly sufficient, with only missing not-found 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?

Schema description coverage is 100% and the single parameter is already documented as 'Blog id (uuid) or name'. The description adds no further syntax, format, or constraint detail beyond the schema.

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

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

States a specific verb (Fetch) and resource (single Polyblog blog), plus the lookup key. Does not distinguish itself from siblings like show_blog_overview or list_blogs, but the 'single by id or name' scope makes its intent reasonably 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?

No when-to-use guidance and no mention of alternatives such as show_blog_overview or list_blogs. The only implied usage is the id-or-name lookup, which is already conveyed by the schema.

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 closed-world, so safety is covered. The description adds genuinely new behavioral context: the comparison is bounded to up to 100 recently edited translations and the result is explicitly marked when the sample is truncated. That sampling/truncation disclosure is exactly the kind of thing annotations cannot express.

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

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

Two tight sentences with zero filler. The scope is front-loaded in the first sentence and the important sampling/truncation caveat follows immediately.

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-parameter read-only audit tool with an output schema, everything the agent needs is present: the resource, the scope, the comparison basis, the sample cap, and the truncation signal. Return-value details are appropriately left to the output schema.

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% with a single well-documented blogId parameter, so the baseline is 3. The description adds only the minor qualifier that the blog must be organization-owned, which is not in the schema, but it does not extend the parameter's meaning further.

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 ('Summarize multilingual article coverage') plus the exact scope ('one organization-owned Polyblog blog'). This is clearly distinguishable from siblings like list_article_translations or show_blog_overview, which enumerate rather than summarize coverage.

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

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

The description implies the use case (auditing a blog's locale coverage) and gives context about what it compares, but never states when to prefer this over list_article_translations or list_blogs, nor any exclusions or prerequisites. Usage is inferable but not explicit.

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 (readOnly, openWorld, idempotent, non-destructive). The description adds genuine behavioral specifics beyond them: it reads /sitemap.xml from customDomain, follows a sitemap index one level deep, and returns a bounded sample. However, the stated 'at most 25' cap conflicts with the maxUrls parameter (default 500, max 2000), leaving the actual return bound ambiguous.

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 dense sentences with no filler, and the core action plus traversal depth is front-loaded before the consumer note. It packs a lot into little space, slightly at the cost of the cap ambiguity.

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

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

An output schema exists, so return shape needn't be explained, and annotations carry the safety profile; the description covers source, traversal depth, and purpose. The only gap is that it never reconciles its 25-URL sample language with the maxUrls parameter.

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 blogId, locale, and maxUrls, which sets a baseline of 3. But the description introduces 'at most 25 safe sample URLs' while maxUrls permits 500 default and 2000 maximum, injecting contradictory meaning about the cap rather than clarifying it.

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

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

The description names a specific verb (summarize URLs), a specific resource (the blog's customDomain /sitemap.xml), and even the traversal mechanism (following a sitemap index one level). It is clearly distinguishable from sibling article/blog tools and tells an agent exactly what will be fetched.

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 downstream consumer ('Used by generate_article as the allowed internal-link pool'), which implies the primary use case, but gives no explicit when-to-use/when-not guidance relative to alternatives like search_articles or get_article for link sourcing.

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 (readOnly, idempotent, non-destructive, closed-world). The description adds useful behavior: a 100-item cap, a truncation marker in the result, and that returned data is 'safe article metadata' plus translation method. That is meaningful context beyond the annotations, though permissions and error behavior remain unstated.

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 core action and limit, then the optional comparison. No filler, though the 'Pass blogId' clause reads slightly like schema duplication.

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-value detail isn't required, and annotations plus description cover safety and limits. The main remaining gap is the absence of usage routing against sibling read tools, but for a bounded 2-param read tool this is nearly complete.

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

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

Schema coverage is 100%, so the schema documents both parameters. The description nonetheless adds semantic value: it clarifies that blogId triggers a comparison against 'at most 100 configured locales' and yields missing-translation info, which is more than the schema's one-line parameter note conveys.

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 locale versions of one article') and names the grouping key `originalArticleId`. It distinguishes itself from read siblings like get_article or search_articles by scoping to translations of one source article, though it doesn't explicitly name an alternative.

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?

Implies usage — you call it to enumerate translations of an article, and optionally pass blogId to compare against configured locales. But it gives no explicit when-to-use vs get_article or get_blog_localization_summary, and no exclusions.

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. The description adds valuable behavioral context beyond that: the result is a 'bounded page', the returned fields (id, name, custom domain), and the cursor continuation pattern. This is useful operational detail not present in structured fields.

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

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

Three tight sentences with zero waste, front-loading the purpose and then covering return shape and pagination mechanics. Every sentence earns its place.

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

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

An output schema exists, so return-value explanation is optional; the description still summarizes the return shape helpfully. Together with annotations and schema, this is nearly complete, though the absence of explicit when-to-use guidance leaves a minor 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?

Schema coverage is 50%: cursor is documented in the schema, but limit lacks a description there. The description compensates by explaining that cursor is a continuation token ('Pass the returned cursor to continue'), adding meaning beyond the schema. Limit's default/max behavior is still not fully clarified, but the description does useful work on the undocumented parameter.

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

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

States a clear verb+resource ('List Polyblog blogs') with scope ('the authenticated tenant has access to'). It is easily distinguished from get_blog (singular) and siblings like search_articles or list_topic_ideas.

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 pagination instruction ('Pass the returned cursor to continue') implies iterative usage, but there is no explicit when-to-use guidance versus get_blog or other listing siblings. Usage context 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 readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered without description help. The description adds that filtering is optional and enumerates returned fields, but says nothing about the cursor/pagination behavior despite a cursor parameter existing, which is the main behavioral gap for a list endpoint.

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 core operation front-loaded and the workflow hint last. The returned-fields sentence is partially redundant given an output schema exists, but it is short and does not bloat the definition.

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

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

With an output schema present, the description need not explain return values, and it correctly focuses on filters and the downstream generate_article link. It is nonetheless incomplete for a paginated list tool: the cursor parameter and any page-size/paging expectations go unaddressed in both the description and the schema.

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 60%: status and minScore carry schema descriptions, while limit and cursor have none. The description echoes the status/minScore semantics (including the 0-10 score range implied by 'minimum score') but adds nothing for limit or cursor, so it does not compensate for the undocumented parameters. Baseline 3 is warranted.

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 saved topic ideas for a blog') plus the two supported filters, so the agent knows exactly what this returns. It stops short of explicitly contrasting with refresh_topic_ideas or set_topic_idea_status, which are the closest siblings, but the operation is unambiguous from the name and text.

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 provides a useful forward route ('Use the id with generate_article to write the article'), which tells the agent what to do next with the result. However it gives no guidance on when to pick this over refresh_topic_ideas (to fetch new ideas) or set_topic_idea_status (to change the status field it surfaces), leaving the sibling selection 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?

Adds substantial context beyond annotations: it spends paid model usage, applies dedupe against published articles, persists results, suppresses raw source errors, and caps returned ideas at five. These are behavioral facts not derivable from the annotations (which only say readOnly=false, destructive=true, openWorld=true, idempotent=false).

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

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

A single dense sentence plus a short imperative sentence; it is front-loaded with the core action and keeps every clause meaningful. Slightly long but well-earned given the multi-step behavior described.

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 the full pipeline, side effects (persistence, paid usage), output shape (aggregate counts, max five ideas), and error suppression. An output schema exists so return format need not be re-explained. Given the destructive+non-idempotent+open-world annotations and 7 params, this is largely complete, though it could clarify irreversibility or auth requirements.

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 parameters are fully documented in the schema (defaults, ranges, nested sources object). The description adds no parameter syntax or meaning beyond what the schema already provides, so baseline 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?

States a concrete multi-step pipeline (fetch, score, dedupe, persist) with a specific resource (topic ideas). Clearly distinguishable from list_topic_ideas (read-only listing) and set_topic_idea_status, which the name and description implicitly separate.

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?

Tells the agent to 'confirm sources and limits first,' which is a usable precondition. However it doesn't name alternatives (e.g., list_topic_ideas vs this refresh) or state when-not-to-use, so it falls short of the explicit routing that earns 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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds value beyond that by disclosing the return shape (Markdown table with id, title, locale, slug, published) and the cursor-based pagination contract, which the annotations do not 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?

Two tight sentences: the first front-loads the operation and filters, the second covers output and pagination. No filler or redundancy.

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, return values need not be explained, yet the description adds a helpful summary of the tabular result and pagination. It is complete for invocation; only the absence of routing guidance to sibling fetch tools keeps it from being fully self-sufficient.

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 high (83%), so the schema already documents slug, blogId, locale, cursor and published. The description restates four of those filters and adds no format or syntax detail (e.g. how 'published' interacts with locale), and omits limit entirely. Baseline 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?

States a specific verb (Search) and resource (Polyblog articles) and enumerates the filter dimensions. It is clearly distinct from get_article and list_article_translations, but it never names an alternative to disambiguate when a single-article fetch is preferable.

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: filters are optional, and the pagination instruction ('Use the returned cursor to page through results') gives a concrete follow-up action. However, there is no explicit when-to-use guidance versus get_article or list_article_translations, and no statement of what happens with zero filters.

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 mutation profile (readOnly=false, idempotent=true, destructive=true); the description adds a scope guarantee beyond them — 'Only the status (and optionally the article it produced) is changed' — and discloses a side effect that is not in annotations, namely that `dismissed` suppresses the idea from future suggestions. It does not explain the destructive aspect flagged by the annotation (e.g. whether clearing the article link is what makes it destructive).

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 filler, and the core action and its three states are front-loaded before the scope-limiting caveat. Every clause carries 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?

With an output schema present, return values need not be described. All three parameters are schema-documented, the mutation semantics are partly covered by annotations, and the description fills the remaining gaps (state meanings, side effect on suggestions, blast radius), so an agent has everything required to call it correctly.

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

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

Schema description coverage is already 100%, so the baseline is 3. The description still adds meaning over the raw schema by defining what each enum value means operationally and by confirming that usedForArticleId is only meaningful alongside `used`, which helps an agent avoid a meaningless combination.

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

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

The description names a concrete verb (move/set the lifecycle status) and a concrete resource (a saved topic idea), and enumerates the three target states. That vocabulary is specific enough to separate it from the read-only siblings list_topic_ideas and refresh_topic_ideas 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?

It gives explicit when-to-use conditions for each value: `used` once an article has been written, `dismissed` to keep the idea out of future suggestions, `new` to reset. It does not, however, point to alternative tools such as list_topic_ideas or refresh_topic_ideas for the cases where this tool is the wrong choice.

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 bar is lower. The description adds real context beyond them: the operation replaces (not appends to) existing lists, `clear: true` wipes all sources entirely, and feeds must be public HTTPS. It does not detail auth/permission requirements.

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

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

Three tight sentences with the replacement behavior front-loaded, followed by the prerequisite and the parameter summary. No filler and no repetition of the schema.

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

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

With an output schema present and full annotation coverage, the description needn't explain return values. It covers the mutation semantics, the clear escape hatch, the prerequisite, and the downstream dependency, which is everything an agent needs 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 the baseline is 3, but the description adds combination semantics the schema does not: you pass `reddit` and/or `rss`, or `clear: true` to wipe everything. This clarifies how the four parameters interact rather than merely restating them.

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 (Replace/Set) and resource (Reddit subreddits and/or public HTTPS RSS feeds for topic research), and names the downstream sibling refresh_topic_ideas. An agent can immediately distinguish this from refresh_topic_ideas or list_topic_ideas.

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?

Provides a clear prerequisite ('Confirm the complete replacement lists before calling') and clarifies the downstream relationship to refresh_topic_ideas. It does not explicitly state when-not to use it versus alternatives like list_topic_ideas, so it stops short of the top score.

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 read-only, idempotent, non-destructive behavior. The description adds useful behavioral context beyond that: the preview is 'focused' and returns publication state, metadata, and a bounded excerpt, which helps set expectations. It doesn't contradict annotations.

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

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

A single, front-loaded sentence states the verb, resource, and key outputs with no filler or repetition of the title. Every clause contributes.

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-parameter, read-only tool with an output schema present, the description is largely sufficient: it names the input requirement and the preview contents. The only slight gap is not clarifying the difference from the full-article getter, which matters for routing but not for invocation.

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

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

Schema description coverage is 100% for the only parameter articleId (including type and length), so the schema carries the parameter meaning. The description adds that the article must be 'known,' but no additional parameter semantics 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?

The description uses a specific verb ('Render') and resource ('known Polyblog article'), and adds the output contents (publication state, metadata, bounded excerpt) so its purpose is clear. It does not explicitly contrast with sibling get_article or show_blog_overview, so it stops short of full differentiation.

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

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

The phrase 'for a known Polyblog article' implies the tool is for articles whose ID you already have, not for discovery. It does not state when to prefer this over get_article or show_blog_overview, nor any exclusions, so usage 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds the return-content scope ('domain, locales, and up to ten recently edited articles') but does not disclose error behavior, permission requirements, or output format details. This is adequate but not rich beyond 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?

The description is a single, well-structured sentence that front-loads the action and resource, then specifies the output scope. Every part contributes value, and there is no redundant or filler content.

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 tool's simplicity (one required parameter, full schema coverage, and an output schema), the description is sufficiently complete. It names the key content elements an agent needs to understand what the overview contains, and the output schema handles return-value details.

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 sole required parameter, blogId, is already described as 'Polyblog blog id to render, at most 200 characters.' The tool description does not add new meaning beyond the schema, 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?

The description uses a specific verb ('Render') and a specific resource ('compact overview for a known Polyblog blog'), and it enumerates the included content (domain, locales, up to ten recently edited articles). This clearly differentiates it from siblings like get_blog or get_blog_localization_summary by focusing on the compact overview rendering 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 description implies a prerequisite by saying 'known Polyblog blog,' but it offers no explicit guidance on when to choose this tool over alternatives such as get_blog or get_blog_localization_summary. There are no stated exclusions or comparison points with sibling tools, leaving the agent to infer usage context.

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=false and openWorldHint=true, but the description adds genuinely new behavioral context: the merge/preserve semantics, that `published` toggles the public page state, and that every update fires an `article.updated` webhook. Webhook side effects and public-page exposure are not derivable 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?

Three short sentences, front-loaded with the operation and semantics; each sentence adds distinct information (merge behavior, publish toggle, webhook) with no redundancy or 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 mutation tool with annotations and an output schema, the description covers the essential non-obvious behaviors: partial update, publish/unpublish side effect, webhook emission. It stops short of noting permission requirements or whether changing `format` alters how `content` is interpreted, which would be the remaining gaps.

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

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

Schema description coverage is only 11% — eight of nine parameters (slug, title, author, format, content, categories, description) are undocumented in both schema and description. The description explains only the general merge behavior and calls out `published`; it does not compensate for the large coverage gap on the remaining fields.

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 ('Partially update an existing Polyblog article by id'), and the qualifier 'partially' plus 'only the fields you pass are changed' precisely distinguishes it from a full replacement or from create/delete sibling operations. An agent can identify the operation 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 context is implied by the PATCH-style semantics ('only the fields you pass are changed'), which tells the agent this is for targeted edits rather than rewrites. However, no alternative is named (e.g., create_article, delete_article, get_article) and no preconditions or when-not-to-use guidance is given.

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