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

With no annotations provided, the description bears the full burden and does an excellent job. It discloses draft behavior (find without draft:true returns only published state), public read access via /api/agents, the full MCP capability set (find, create, update, delete), and a strong warning that delete is hard-delete not caught by the admin Trash. It also notes field constraints like localization and character limits. No contradictions with annotations (none exist).

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, dense run-on paragraph of about 200 words, mixing resource fields, workflow notes, and warnings without clear segmentation. It front-loads with 'FAQ entries' but then cascades into many semicolon-separated points that are hard to parse quickly. It could be broken into bullet points or sections for better scannability. It is not concisely structured.

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 there is no output schema, the description should clarify return shape or pagination behavior. While it covers many operational aspects (drafts, permissions, delete), it does not describe the response format (e.g., array of documents, fields included) or how pagination parameters interact with results. Since the schema covers parameter semantics, the missing piece is the output contract. The description is not fully complete for a complex find tool with 10 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?

The input schema has 100% description coverage for all 10 parameters, providing baseline explanations for each. The description adds meaningful context for the `draft` parameter (explaining that without draft:true it returns only the published state) and implicitly ties `where` filtering to the field descriptions. However, it does not add significant detail for other parameters such as `page`, `limit`, or `sort`, which remain schema-defined. This meets the baseline but does not elevate beyond 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 clearly identifies the resource as 'FAQ entries' and elaborates on the exact fields (question, answer, categories) and its usage in the /faq system page and faqBlock. It also names the collection ('faqs') and lists the MCP capabilities. This is specific enough to distinguish it from siblings like findPages or findPosts without ambiguity.

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 provides practical usage context: it explains the draft/publish workflow, the need to use `_status:"published"` for live content, the existence of the `schedulePost` tool for future dates, and the permanent delete warning. However, it does not explicitly state when to use this tool versus alternative find tools (e.g., 'use for FAQ content only'), nor does it compare to siblings. This is adequate but not explicit routing.

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