Capterra product reviews: author, headline, rating.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based result page, default 1. | |
| product_id | Yes | Capterra product id, the numeric id in a /p/{id}/{slug}/ URL, e.g. 135003. |
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | The tool result payload (shape varies per tool; see each tool's docs resource). |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and scope are covered. The description adds no behavioral context of its own - no pagination notes (despite a page param), no result ordering, no coverage limits.
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?
A single compact sentence with no padding, and the resource identity is front-loaded. It is efficient, though the terseness borders on under-specification rather than true conciseness.
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 simple two-parameter read tool with annotations and an output schema, the description covers the essential minimum. It omits any mention of paging behavior or the fact that reviews are scoped to a single product_id, but not much is strictly required.
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% with only two parameters, and the schema fully documents both product_id and page. The description's brief field mention ('author, headline, rating') describes output, not inputs, so it adds nothing to parameter understanding; 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?
The description names the resource (Capterra product reviews) and the fields returned, so an agent can infer the subject matter. However, it uses no verb (fetch/list) and does not distinguish this from sibling capterra_product or the many other *_reviews tools, leaving the purpose only implied.
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?
No when-to-use guidance is given. The description never states that a product_id is required, nor how this differs from capterra_product, which likely also surfaces reviews. Nothing routes the agent among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
