mcp

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: it returns the page markdown exactly as authored, ignores anchors, and returns the whole 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 longer than minimal, but every sentence earns its place by covering purpose, usage order, return behavior, and exclusions. It is front-loaded with the core purpose and uses short, direct sentences.

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 one required parameter, no output schema, and clear annotations, the description covers everything needed to call the tool correctly: what it returns, when to call it, prerequisites, and boundaries. The sibling context reinforces the workflow guidance.

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 schema already explains the url parameter. The description adds extra value by giving concrete URL/path examples and explicitly stating that anchors are ignored and the whole page is returned, which clarifies edge-case behavior.

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 and resource ('Read the full source markdown of a Capawesome documentation or blog page') and clearly differentiates itself from search_docs and list_blog_posts by noting it needs an exact URL and is not for finding pages. This leaves no ambiguity about what the tool does.

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 explicitly says when to use the tool ('after search_docs to read a page end to end before writing code'), when not to use it ('Do not use this to find a page'), and names the alternatives (search_docs, list_blog_posts). It also scopes usage to capawesome.io pages, giving clear selection criteria.

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.