Ahrefs MCP Server

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

No annotations are provided, so the description must fully disclose behavioral traits. It mentions 'retrieves' (implying read-only) and hints at data grouping, but fails to cover critical aspects like authentication needs, rate limits, pagination, error handling, or the format of returned data. For a tool with no annotations and no output schema, this leaves significant gaps in understanding how the tool behaves in practice.

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 two sentences: the first states the purpose, and the second provides a usage note. It is front-loaded with the core functionality, but the second sentence feels like a workaround rather than integrated guidance. While not verbose, it could be more structured by embedding the schema note within the purpose explanation.

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 complexity (historical data retrieval with grouping), lack of annotations, 0% schema description coverage, and no output schema, the description is incomplete. It omits details on parameter semantics, behavioral traits like rate limits, and the structure of returned data. For a tool with 4 parameters and no structured support, this leaves too much undefined for effective use.

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 description coverage is 0%, so the description must compensate by explaining parameters. It mentions 'domain or URL' (hinting at 'target'), 'date range' (hinting at 'date_from' and 'date_to'), and 'time interval' (hinting at 'history_grouping'), but does not specify data formats (e.g., date strings like YYYY-MM-DD), allowed values for 'history_grouping', or whether 'date_to' is optional. With 4 parameters and no schema descriptions, this partial mapping is insufficient.

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 states the tool's purpose: 'Retrieves the historical URL rating data for a specified domain or URL over a defined date range, grouped by a chosen time interval.' It specifies the verb ('retrieves'), resource ('historical URL rating data'), and scope ('domain or URL', 'date range', 'time interval'). However, it does not explicitly differentiate from sibling tools like 'site-explorer-domain-rating-history' or 'site-explorer-metrics-history', which might offer similar historical data for different metrics.

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 includes a usage note: 'Use doc tool first to get the real input schema.' This provides some guidance on prerequisites, but it does not explain when to use this tool versus alternatives (e.g., other 'site-explorer-*' tools for historical data) or any exclusions. Without explicit context on when this tool is appropriate compared to siblings, the guidance is incomplete.

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