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

With no annotations, the description carries the full burden and does well: it discloses the exact payload (title, publish date, summary, full body), the HTML-to-text conversion with headings/lists/links preserved, the canonical URL, and the not-found behavior for unknown slugs. It omits auth or rate-limit context, but for a public read tool that is a minor gap.

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

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

Two tight sentences, front-loaded with the verb, resource, and required input key before describing the return payload and edge case. 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?

No output schema exists, so the description usefully specifies the return contents and the not-found case, and the single parameter is fully documented in the schema. An agent has everything needed to call it and interpret the result.

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 there is a single required slug parameter whose schema description already says it is discovered via list_articles or search_refined_element_knowledge. The description repeats that guidance without adding format or syntax detail, 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 ('Read one full Refined Element blog article by slug') with explicit scope ('one full ... article'), which cleanly separates it from the list/search siblings. An agent can tell it fetches a single article body rather than a collection.

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 context: slugs come from list_articles or search_refined_element_knowledge, so the agent knows the retrieval path. It stops short of stating when not to use this tool (e.g., versus get_paid_playbook), so it is strong but not fully routing-complete.

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

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

With no annotations, the description carries the full burden and does so: it discloses the exact return shape (title, summary, topic, audience, ordered steps with action + explanation), the premium-slug branch behavior, and the unknown-slug not-found case. That edge-case and return-content coverage is well beyond anything structured fields 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?

Three tight sentences, front-loaded with the action and scope, followed by return content and then routing/error guidance. Every clause earns its place 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?

With no output schema and no annotations, the description fully compensates by describing the returned fields, the premium-path behavior, and the not-found outcome, plus where to obtain valid slugs. An agent has everything needed to call and interpret 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?

Schema coverage is 100% and the single slug parameter is fully documented in the schema with the same example the description uses. The description adds no syntax, format, or constraint detail beyond the schema, 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 specific verb (fetch) and resource (one full free checklist) plus the source pack and slug identifier. It explicitly distinguishes itself from get_paid_playbook for premium content, so an agent can route correctly 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?

Names both the input source ('Get valid slugs from search_refined_element_knowledge') and the alternative for premium slugs (get_paid_playbook). When-to-use and where-to-get-inputs are both explicit, leaving nothing 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?

With no annotations, the description carries the full burden and does so well: it discloses the L402 paywall, the typical cost (100 sats), the HTTP 402 challenge and its invoice/macaroon response, and the mandatory two-call handshake with the preimage as proof of payment. This is exactly the behavioral context an agent needs before invoking a payment-gated tool.

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

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

Front-loaded with the one-line purpose, then the gating mechanism, then the procedural flow, so each part is findable. It is slightly dense in the middle (payment-server URL and 402 detail) but every sentence carries actionable information.

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

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

For a payment-gated, stateless-looking tool with no output schema, the description covers gating, cost, failure mode (402 with challenge payload), and the complete retry path. An agent has everything required to invoke it correctly on both passes.

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 three parameters are already documented, giving a baseline of 3. The description adds real meaning beyond the schema by explaining that macaroon and preimage are omitted on the first call and required on the second, clarifying the two-phase contract rather than just restating field names.

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

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

States a specific verb and resource ('Retrieve one premium item from the Ask Refined Element pack by slug') and names the sibling that discovers slugs, so it is immediately distinguishable from search_refined_element_knowledge and the free get_article/get_checklist 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?

Gives explicit sequencing ('Call this tool FIRST with only the slug', then 'call this tool AGAIN with the same slug plus the macaroon and the payment preimage'), names the discovery alternative, and even points at the recommended Lightning payment helper.

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

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

No annotations are present, so the description carries the burden. It discloses ordering (newest-first) and the result cap (up to 50), and because there is no output schema it usefully describes the return shape. It does not address permissions, pagination beyond the cap, or what happens when no articles match, which keeps 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?

The description is front-loaded with the core verb and payload, and the follow-up get_article call is placed before the less important cap details. It is slightly redundant in restating the limit/ordering facts already in the schema, but there is no filler sentence.

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 list tool with no output schema, the description supplies everything an agent needs: the fields returned, the ordering, the cap, and the natural follow-up tool. Nothing required 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 limit parameter is already documented there, including default 10, max 50, and newest-first ordering. The description repeats that same information ('Returns newest-first, up to 50 (default 10)') without adding syntax or behavior 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?

States a specific verb and resource ('List the most recent posts from the Refined Element blog') and enumerates exactly what each item contains: title, publish date, one-line summary, and slug. It also distinguishes itself from the sibling get_article, which returns the full text rather than the index.

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-to-use ('Use this to see what Refined Element has published on Xperience by Kentico, GEO, AI-driven development, and agent commerce') and names the alternative/next step with its argument shape ('then call get_article(slug) for the complete text'). The routing decision between the two tools is fully stated.

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

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

With no annotations, the description carries the full burden. It does disclose useful non-obvious traits: a human ('Mike') reads every request personally, and priority is free with no payment. It does not disclose what happens after submission (confirmation behavior), whether data is stored/shared, or any rate limits — notable gaps for a mutation tool that transmits contact data to a third party.

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?

Purpose is front-loaded and the passage is a tight four-sentence block with no filler. There is mild redundancy — 'priority is free, no payment required' restates the schema description — but overall it is efficient and readable.

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

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

For a 5-parameter submission tool with no output schema and no annotations, the description covers inputs and recipient well but omits return/confirmation behavior and error semantics. An agent knows how to call it but not what to expect back, which is a meaningful completeness 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 already 100%, so the baseline is 3, but the description adds genuine meaning: it tells the agent what to put in 'message' (what you're building, your Kentico version, timeline) and clarifies that priority=true flags urgency at no cost. This enriches the highest-value field beyond the schema's generic 'include enough context'.

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 ('Send a consultation request') and identifies the recipient (Mike Rahel at Refined Element), then scopes it to three concrete domains: Kentico upgrades, AI-driven development, and GEO work. An agent can immediately tell this is a write/send action, distinct from every read-only sibling (get_article, list_articles, etc.).

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 subject-matter scoping ('for Xperience by Kentico upgrades, AI-driven development, or agent-first (GEO) work') makes the intended use context clear. However, it never says when NOT to use it or points to an alternative (e.g., search_refined_element_knowledge for a quick answer instead of contacting a human), so the routing 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?

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses ranked-result formatting, that FAQ/case study/service matches have no slug and return content inline, that premium items return only a summary plus slug, and that bare queries produce a type-grouped index. It does not mention auth requirements, rate limits, or pagination beyond the limit parameter, which are minor gaps.

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

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

Dense but well front-loaded, leading with scope and content types before the retrieval mechanics. The omitted-query browse behavior is stated twice (once in the body, once implicitly via the schema-mirroring phrasing), a small redundancy that keeps it from a perfect score.

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

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

There is no output schema, so the description must explain return values itself — and it does, describing ranked matches, inline content for slug-less types, and summary-plus-slug for premium items, plus the index fallback. Nothing needed to call or interpret the 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 description coverage is 100%, so the baseline is 3. The description restates the query-omission behavior and the topic/audience filtering at a conceptual level but adds no syntax or matching-rule detail (e.g., how keyword search handles multi-term queries) beyond what the schema already documents.

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 (full-text search over the Ask Refined Element knowledge pack) and enumerates the exact content types covered, including the topical domains. An agent can distinguish it from sibling retrieval tools like get_article or get_paid_playbook 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?

Explicitly positions itself as the entry point when Refined Element expertise is needed, explains the browse mode when the query is omitted, and routes to the correct follow-up tool per content type (get_article for blog, get_checklist for free checklists, get_paid_playbook for premium). Conditions and alternatives are all stated.

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