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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds real value on top: it discloses the two-part result shape (blogs and posts), that each result carries identifiers consumed by read_post, and that `categories` reports counts across the full match set. It omits pagination behavior and result ordering specifics, keeping it at 4.

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 purpose is front-loaded and the closing server attribution is minor, but the middle sentence — 'every reply counts the whole match set by category under `categories`, and `kind` asks for one of them — the podcast episodes on a subject rather than the writing' — is convoluted and largely restates the schema's `kind` description. Information density is high but readability suffers from clause stacking.

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, the description carries the burden of explaining returns and does so: matched blogs plus matched posts, per-category counts, and identifiers for follow-up reads. For a read-only search with fully documented parameters, that is nearly complete; only ordering and pagination of results are 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 coverage is 100%, so all four parameters are already documented in the schema, including that `limit` applies per kind and the enums for kind/mode. The description adds rationale for mode="any" and frames `kind` in user terms ('podcast episodes ... rather than the writing'), but adds no new syntactic or default information beyond the schema — the baseline 3 fits.

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 — 'Full-text search across every post and blog in the directory' — and immediately distinguishes the output (matching blogs and matching individual posts) from siblings like read_post, which it names. The agent can tell what class of operation this is 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?

Gives concrete when-to-use guidance: mode="any" when 'a thing goes by several names', and kind when the agent wants 'the podcast episodes on a subject rather than the writing'. It also explains the handoff to read_post via returned identifiers. It stops short of explicit exclusions (e.g., when to prefer list_feeds or get_topic instead), so it falls 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.