mcp

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

Beyond the readOnlyHint annotation, the description reveals important behaviors: it returns title, URL, and markdown (excluding build metadata), ignores anchors, returns the whole page, and requires an exact URL/path. This exceeds what annotations alone 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?

The description is somewhat verbose but every sentence carries essential guidance (usage, return format, limitations, sibling differentiation). No fluff or redundancy; the structure flows logically from purpose to usage to caveats.

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, the description covers all needed context: what it returns, when to call it, what not to do, and domain restrictions. There is no output schema, but the return content is described sufficiently. It fully equips an agent to use the tool 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?

The schema has 100% coverage for the single 'url' parameter, and the description enhances it with concrete examples (both full URL and relative path) and clarifies that anchors are ignored and the entire page is returned. This adds significant semantic value.

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 explicitly states the tool reads the full source markdown of a Capawesome documentation or blog page, and clearly distinguishes itself from sibling tools by specifying its role as a follow-up to search_docs and not a finder.

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 explicit when-to-use and when-not-to-use guidance: use after search_docs for full page content, use search_docs or list_blog_posts for discovery, and avoid pages outside capawesome.io. No ambiguity remains.

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 and openWorldHint=true, but the description adds valuable behavioral context: the exact limit (20), ordering (newest first), return fields (title, description, date, categories, url), and the implication that it returns snippets (not full articles) by directing to get_doc_page. This goes beyond the annotations without contradicting them.

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 compact and front-loaded: it states the core action first, then usage conditions, then return format, then a negative usage note. Every sentence earns its place, with no redundancy or fluff.

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 zero parameters and no output schema, the description is fully sufficient. It specifies the result set size, ordering, fields returned, how to access full content (via get_doc_page), and when to avoid this tool. An agent has everything needed to decide whether and how 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?

The tool has zero parameters, so the baseline is 4. The description correctly doesn't attempt to explain parameters since none exist, and it implicitly conveys that no arguments are needed by stating the action without any prerequisites. This is appropriate for a parameterless tool.

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 explicitly states the verb, resource, and limit: 'List the 20 most recent posts from the Capawesome blog, newest first.' It also differentiates from siblings by specifying when to use it (recent releases, announcements, etc.) and when not to (topic questions), making the tool's purpose unmistakable.

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?

Clear guidance on when to use: 'Use this when the question is about what is new...' and explicit exclusion: 'Do not use this to answer a topic question...' It also names the alternative `search_docs` and explains the reason (feed only has newest posts). Additionally, it routes the agent to `get_doc_page` for full articles, covering the full usage path.

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 and destructiveHint=false; the description adds useful behavioral context by describing the return shape, best-matching section behavior, and that results are also attached as structured content. There is no contradiction with 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 longer than average, but every sentence earns its place: it front-loads the purpose, then covers return behavior, structured content, and explicit alternatives/exclusions. 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?

The tool has an output schema, full parameter schema coverage, and annotations; the description completes the picture with usage guidance, boundaries, alternatives, and return-field details. Nothing an agent needs to invoke 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% and every parameter already has a clear description, including examples and enum values. The description mostly reinforces the keyword-based scope rather than adding new parameter-level meaning, 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 and resource: searching Capawesome documentation, guides, and blog by keyword. It clearly distinguishes itself from siblings by naming get_doc_page and list_blog_posts and by excluding cloud_* tools.

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 says 'Use this first' for documentation questions and provides concrete when-not-to-use guidance, including alternatives such as get_doc_page and list_blog_posts. The description fully routes an agent to the correct tool for each scenario.

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