Semrush MCP

by mrkooblu

Overview Schema Related Servers Score Discussions

TypeScript

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.2.0
Disambiguation4/5
Each tool targets a specific entity and data type (e.g., domain organic keywords vs subdomain organic keywords vs URL organic keywords), with descriptions clarifying the exact scope. Some overlap exists between overview and specific tools, but overall distinct.
Naming Consistency5/5
All tools follow a strict 'semrush_{entity}_{detail}' snake_case pattern (e.g., semrush_backlinks_anchors, semrush_domain_organic_keywords). No mixed conventions or irregular naming.
Tool Count2/5
With 77 tools, the server is overly granular for a typical MCP interface. While covering a broad domain, the high count can overwhelm agents and make tool selection error-prone, contrary to MCP best practices.
Completeness5/5
The tool set comprehensively covers Semrush's core offerings: keywords, backlinks, traffic, audience, site audits, and project management at multiple levels (domain, subdomain, subfolder, URL). No obvious functional gaps.
Average 2.9/5 across 77 of 77 tools scored. Lowest: 2.1/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds no behavioral context beyond repeating the word 'ranking data.' It doesn't explain output format, pagination, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise (one short sentence) but at the expense of necessary detail. Under-specification makes it inadequate for effective tool selection.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and only a vague description, the tool definition leaves significant ambiguity. It does not specify what 'ranking data' entails, how limit works, or what the database parameter defaults to.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain any parameters (url, database, limit) or their roles, leaving the agent without essential context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool gets 'ranking data for a specific URL,' which is clear but vague. It doesn't differentiate from sibling tools like semrush_url_organic or semrush_url_rank_history that also deal with URL rankings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus its many siblings. There is no mention of use cases or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the safety profile is known. However, the description adds no further behavioral context such as what the summary stats contain, data freshness, or pagination, beyond 'summary stats'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence but is under-specified, lacking necessary details for effective tool use. Conciseness is achieved at the expense of informativeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 parameters, no output schema, and many sibling tools, the description is highly incomplete. It fails to describe what the overview includes, parameter formats, or usage context, leaving an agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, with 3 parameters (target, target_type, limit). The description mentions only 'target' but does not explain target_type enum values, limit semantics, or provide any additional parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves overview summary stats for backlinks for a target. The verb 'Get' and resource 'backlinks overview summary stats' are specific, but it does not explicitly distinguish from sibling tools like semrush_backlinks, which may provide more detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., semrush_backlinks, semrush_backlinks_anchors). The description does not mention use cases, prerequisites, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, so the agent knows this is a destructive operation. However, the description adds no further behavioral context, such as whether deletion is permanent, requires specific permissions, or affects associated data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at five words, which is appropriate for a simple tool. However, the conciseness comes at the cost of missing essential information, making it barely adequate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with one parameter and no output schema, the description lacks critical context: how to obtain the project_id, what happens on deletion, any side effects, and error scenarios. The agent is left with insufficient information to use the tool safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the 'project_id' parameter beyond its schema definition (number, >0). With 0% schema description coverage, the description fails to clarify how to obtain a valid project_id or what format it expects.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Delete a Semrush project'. The verb 'Delete' and resource 'project' are specific. Among sibling tools like create_project, update_project, get_project, list_projects, the purpose is well-distinguished.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives, nor any prerequisites or conditions for deletion. The agent receives no context about project ownership, dependencies, or recovery options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds no behavioral details beyond that, such as potential errors, rate limits, or data freshness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but lacks structure and necessary details. It is front-loaded but sacrifices completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters with no descriptions, no output schema, and no explanation of 'unique', the description is insufficient. It fails to help an agent understand inputs or expected output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the parameters (domain, database, limit). Only 'domain' is implied by the tool purpose. The meaning of 'database' and 'limit' is left unsaid.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it retrieves unique paid ads for a domain, distinguishing it from sibling tools like semrush_domain_paid_keywords (keywords) and semrush_domain_ads_history (history). The verb 'Get' and resource 'unique paid ads' are specific, but 'unique' could be expanded.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as semrush_domain_ads_history or semrush_domain_paid_keywords. The description does not provide context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint and idempotentHint as true, but the description adds no behavioral context (e.g., pagination, rate limits, data scope). It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but lacks structure. It is not verbose, but could be better organized with key information front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and annotations that only cover safety, the description fails to explain what the tool returns (e.g., list of keywords with metrics) or how to iterate using limit. This leaves the agent without sufficient context to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions) and the description does not explain any parameter. The domain parameter is implied but database and limit have no added meaning. This is a major gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves organic keywords for a domain, distinguishing it from sibling tools that handle paid keywords, ad history, or domain overview. The verb 'get' and resource 'organic keywords' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., semrush_domain_organic_unique or semrush_subdomain_organic). No context about prerequisites or limitations is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds no behavioral context beyond the annotation hints, such as what 'historical ranking data' includes (e.g., time range, granularity) or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, very concise. However, it is too terse, sacrificing necessary detail for brevity. It is front-loaded with the core purpose but lacks completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, no output schema, and 0% schema description coverage, the description severely under-informs. It does not explain what 'historical ranking' entails, time range, database meaning, limit behavior, or return format. Incomplete for effective tool use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It does not describe any parameter: domain (required but self-explanatory?), database (default 'us' - what does 'us' mean?), limit (exclusiveMinimum - what does it limit?). No added meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Get' and resource 'historical ranking data for a domain'. It clearly states the tool's function but does not differentiate from siblings like semrush_domain_rank (current rank) or semrush_subdomain_rank_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. Sibling tools include many ranking-related tools with similar names (e.g., semrush_domain_rank, semrush_subdomain_rank_history), and the description offers no criteria for choosing this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds minimal behavioral info beyond 'requires .Trends'. It does not mention output structure, pagination, or any side effects, leaving gaps for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence) and front-loaded with the core purpose. However, the brevity sacrifices necessary detail, making it feel under-specified rather than efficiently compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given five parameters, no output schema, and simple annotations, the description is incomplete. It lacks information on parameter behavior, return format, and how the distribution data is structured, which is essential for an agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanations for the five parameters (target, country, device_type, display_date, limit). An agent would have to infer their meaning from names alone, which is insufficient for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'household size distribution of audience', making the tool's purpose evident. While sibling tools like education_distribution exist, the name and description sufficiently distinguish this tool by the specific property. However, no explicit differentiation is provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage guidance is 'requires .Trends', which is a prerequisite but does not specify when to use this tool vs. alternatives like other distribution tools. No exclusions or context about ideal use cases are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is known to be safe and idempotent. The description adds one behavioral context: the need for a '.Trends' subscription. This is useful but minimal beyond what annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no waste, but it is extremely brief. It earns its place but provides too little information to be considered well-structured for a tool with five parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has five parameters, a required input, and no output schema, the description is critically incomplete. It does not explain what the traffic rank means, how optional parameters affect the result, or what format the output takes. The description fails to provide a usable context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden for explaining parameters. However, it only mentions 'domain' and ignores the other four parameters (country, device_type, display_date, limit). This is insufficient for an agent to use the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get traffic rank for a domain' which is a specific verb and resource, but among many sibling tools (e.g., semrush_domain_rank, semrush_subdomain_rank), it fails to differentiate what makes this tool distinct. The purpose is clear but not unique.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The only extra information is '(requires .Trends)', which is a prerequisite, but it doesn't help an agent decide between this and similar ranking tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds no additional behavioral details such as rate limits, data freshness, or error handling. It merely restates the basic function, offering no extra transparency beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at one sentence, but it sacrifices necessary detail. It is front-loaded but lacks explanatory context that would aid an AI agent. The shortness is a double-edged sword: no fluff, but incomplete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 3 parameters and no output schema, the description is incomplete. It does not describe the output format or provide context on how the tool fits among many backlinks siblings. The agent may need to guess the return structure or appropriate usage scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description does not document any parameters. While the parameter names (target, target_type, limit) are somewhat self-explanatory, the description fails to clarify their meaning or provide examples. It does not add value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get anchor text distribution for a target', which is a specific verb-resource combination. Among sibling tools like semrush_backlinks, semrush_backlinks_overview, and semrush_backlinks_pages, this tool is distinct due to its focus on anchor text distribution. However, it does not elaborate on what constitutes a 'target', leaving some ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention when not to use it, prerequisites, or other helpful context. Users are left to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds no further behavioral context, such as what the ranking represents, how the database parameter affects results, or any limitations. With annotations present, the description falls short.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with 7 words, but it omits important information. It is front-loaded but not appropriately sized given the tool's complexity and lack of other explanatory context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters, no output schema, and many siblings, the description is too sparse. It does not explain the meaning of the returned ranking, the format, or how it differs from similar tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% parameter descriptions. The description only hints at the 'database' parameter ('in a specific database') but does not explain the 'domain' or 'limit' parameters. It adds minimal semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('domain ranking in a specific database'). It is a specific verb+resource pair. However, it lacks differentiation from siblings like semrush_domain_rank_history or semrush_subdomain_rank, which could cause confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the many sibling rank tools. The description does not mention any context for use, alternatives, or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only repeats the action 'Get', which is already implied by the readOnlyHint annotation. No additional behavioral traits are disclosed, such as data freshness, rate limits, or potential side effects beyond what annotations already state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 10 words, achieving high conciseness. It front-loads the core purpose. However, it could include slightly more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and only minimal parameter information from the schema, the description fails to provide sufficient context about the return value format, the meaning of 'database' and 'limit', or any other operational details needed for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero description coverage for its three parameters (domain, database, limit), and the tool description does not explain their meaning or usage. This leaves the agent to infer entirely from parameter names, which may be ambiguous (e.g., 'database' likely refers to a country code but is not clarified).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'PLA (Product Listing Ads) search keywords for a domain', making the purpose specific and understandable. However, it does not differentiate from the sibling tool semrush_domain_shopping_unique, which likely has a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives, such as semrush_domain_shopping_unique or other keyword-related tools. The description lacks any context about prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds only the '.Trends' requirement, which is a prerequisite, not a behavioral trait. It fails to disclose response format, data limits, or any other behavioral details beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence), which is positive, but it sacrifices necessary detail. It front-loads the main action but omits parameter guidance and context. It is appropriately sized for a simple tool but incomplete for a 5-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 parameters, no output schema, 0% schema coverage), the description is severely incomplete. It does not describe what 'audience' refers to, how the output is structured, or any edge cases. With no output schema, this lack of description leaves agents without essential context for choosing and using the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no explanation of any parameters (target, country, device_type, display_date, limit). It does not clarify what 'target' represents or how the optional parameters affect results. The description adds no semantic value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Get income distribution of audience'. It also mentions a prerequisite ('.Trends'). However, it does not differentiate itself from sibling tools like semrush_education_distribution, semrush_household_distribution, or semrush_occupation_distribution, which share similar purpose patterns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a usage condition: 'requires .Trends'. But it provides no explicit guidance on when to use this tool versus alternatives, nor does it specify any context exclusions. The usage is implied but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's safe. However, the description adds no additional behavioral context such as rate limits, pagination behavior, or what happens if the project_id or url is invalid. Without any extra information, the description fails to enhance transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at 5 words, which makes it quick to read. It front-loads the verb 'List'. However, given the number of parameters and the existence of sibling tools, a slightly more detailed description would be beneficial without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters and no output schema, yet the description provides no information about output format, required inputs, or behavior. The annotations cover safety but not functional behavior. The description is incomplete for an agent to effectively call this tool without additional schema inspection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter has a description in the schema. The tool description also does not explain any parameters (project_id, url, limit, page). For a tool with 4 parameters, this is a critical gap. The agent has no guidance on what each parameter does, especially the optional ones like limit and page.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'pages from a site audit', making the basic purpose obvious. However, it does not differentiate from sibling tools like semrush_site_audit_page_detail or semrush_site_audit_issues, which might also involve pages. A more distinct description would improve clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it does not explain that this lists all pages from a specific audit snapshot, nor does it mention prerequisites like having an existing audit. The description simply states what it does without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds no additional behavioral context such as pagination, data freshness, or special requirements, but does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very short (5 words) but not wasteful. It lacks structure but is minimally adequate for a simple tool; however, more detail could be added without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 0% schema coverage, no output schema, and 3 parameters, the description is far too incomplete. It does not explain what the tool returns, parameter details, or any usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions in the schema. The tool description gives no information about what 'subfolder', 'database', or 'limit' mean or their expected formats/values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get unique paid ads for a subfolder', specifying verb and resource. It distinguishes from sibling 'semrush_subfolder_adwords' by adding 'unique', but does not explain what 'unique' means in this context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'semrush_subfolder_adwords' or 'semrush_domain_adwords_unique'. The description provides no context for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds value by noting the '.Trends' requirement, but lacks details on rate limits, pagination, or return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no unnecessary words, but could benefit from more structure given the number of parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and 5 parameters undocumented, the description is insufficient for an agent to understand the tool's full behavior and usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the 5 parameters (target, country, device_type, display_date, limit), relying solely on the schema which lacks descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves 'audience interest categories for a domain', a specific verb+resource, but it does not differentiate from the sibling semrush_audience_insights.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Only mentions a requirement ('.Trends'), but provides no guidance on when to use this tool versus alternatives like semrush_audience_insights, nor any context for exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds no behavioral context beyond what annotations already declare (readOnly, idempotent). No mention of data freshness, limits, or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but too brief to be useful; lacks essential details about usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema or description of return value, leaving the agent uninformed about what the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage and description does not explain 'target' format or 'limit' behavior, leaving parameters ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool gets backlinks for a domain or URL, distinguishing it from other backlinks tools that focus on anchors, categories, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool over sibling backlinks tools like semrush_backlinks_anchors or semrush_backlinks_pages.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, non-destructive, idempotent. Description adds no new behavioral info beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single sentence, concise but too brief to convey necessary details; it is not a model of conciseness due to lack of structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple, the description fails to explain parameters or return value, making it incomplete for an agent to use correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 0% and description provides no explanation of parameters (target, target_type, limit). Agent must infer from type and enum alone, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it retrieves indexed pages with backlink data for a target, but does not distinguish from sibling tools like semrush_backlinks_overview or semrush_backlinks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus other backlink tools; no context about prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-read-only, non-destructive, non-idempotent operation. The description does not add further behavioral context such as default settings or API consumption.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, but it is under-informative and lacks necessary detail, failing to provide value despite its brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (2 parameters, potential side effects) and no output schema, the description fails to cover return values, error conditions, or usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description provides no explanation of the 'url' and 'project_name' parameters, leaving their meaning and purpose entirely unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new Semrush project' clearly states the action (create) and the resource (project), distinguishing it from sibling tools like list, delete, or update projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., update_project, list_projects) or prerequisites like API units or account setup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true, establishing safety. The description adds no further behavioral context (e.g., data freshness, error handling). With annotations present, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence (12 words) that front-loads the purpose. It contains no fluff, though it omits parameter explanations, which slightly reduces clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of 3 parameters, no output schema, and a large set of sibling tools, the description is insufficient. It lacks parameter details, output structure, and differentiation from similar domain tools, leaving the agent ill-equipped to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for its three parameters (domain, database, limit). The description fails to explain the meaning or usage of these parameters, only listing output data types. This does not compensate for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it 'Get domain overview data including organic/paid search traffic, keywords, and rankings', specifying the verb and resource. However, it does not distinguish from sibling tools like semrush_domain_organic_keywords or semrush_domain_paid_keywords, which also deal with domain data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., for a broad overview vs. specific keyword or rank details). No exclusions or context for usage are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so safety traits are covered. The description adds the '.Trends' requirement, which is a behavioral constraint not in annotations. However, it does not disclose rate limits, authentication needs, or output behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the tool's purpose. It is concise with no redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and many sibling tools, the description is too minimal. It lacks information on return values, parameter semantics, and usage context, making it incomplete for effective tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate but fails to provide any parameter details. It does not explain the required 'target', optional 'country', 'device_type', 'display_date', or 'limit' parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get occupation distribution of audience', indicating a specific verb and resource. It distinguishes from sibling tools like semrush_education_distribution by focusing on 'occupation'. However, it does not explicitly differentiate from other demographic distribution tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The parenthetical '(requires .Trends)' indicates a prerequisite but does not explain context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, indicating a safe, idempotent operation. The description adds no behavioral context beyond that (e.g., what data is returned, time range, pagination behavior). 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is extremely concise (5 words), but this brevity sacrifices necessary detail. It is front-loaded but too minimal for a tool with three parameters and no schema descriptions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 3 parameters and no output schema, the description should still clarify pagination or the nature of the history (e.g., crawl dates, statuses). The current description is too vague to allow an agent to confidently invoke the tool without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions. The description fails to explain any of the three parameters (project_id, limit, offset). The agent must rely solely on parameter names and types, which is insufficient for correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Get' and resource 'site audit crawl history', clearly indicating the tool retrieves a list of past crawl history. Among sibling tools like 'semrush_site_audit_info', 'semrush_site_audit_issues', etc., this focuses on history, distinguishing it adequately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus other audit tools (e.g., snapshots, issues, pages). No mention of prerequisites like needing a project ID or typical use cases. The agent is left to infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description adds no behavioral context. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is efficiently short and front-loaded. However, it could be more informative without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and many siblings. The description does not clarify what 'site audit information' includes, making it hard for the agent to select correctly. More detail is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only implies that project_id identifies the project. It does not explain what project_id represents or how to obtain it, leaving the agent with minimal understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool gets site audit information for a project, but it is vague and does not differentiate from sibling tools like semrush_site_audit_history, semrush_site_audit_issues, or semrush_site_audit_pages. The verb 'get' and resource are clear, but specificity is lacking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. With many sibling site audit tools, the agent receives no hints about selecting this specific one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds no extra behavioral context (e.g., scope of metadata, pagination, or required prior state), so it meets the baseline given annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (5 words), but such brevity comes at the cost of completeness; it is not optimally concise because it omits necessary information for effective use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (single param, no output schema) and many sibling tools, the description is too sparse; it does not explain what 'issue metadata' entails, how it relates to other site audit tools, or any operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no explanation of the single parameter 'project_id' (e.g., what it represents or how to obtain it), failing to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and resource ('issue metadata for site audit'), but does not differentiate from many sibling site audit tools such as semrush_site_audit_page_detail or semrush_site_audit_snapshots, so specificity is moderate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage context is provided; the description does not indicate when to use this tool versus alternatives, nor does it mention any prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds no additional behavioral context (e.g., rate limits, data freshness). It is consistent but not informative beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wordiness. However, it is too brief and lacks necessary details, which reduces the value of its conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no output schema, and no param descriptions, the one-sentence description is insufficient. It does not cover what the tool returns, any constraints, or expected behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 3 parameters with 0% description coverage. The description does not explain any parameter meanings, such as what subdomain format is expected, what database values are valid, or how limit behaves.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get organic keywords for a subdomain' clearly states the verb and resource. It distinguishes from sibling tools like semrush_domain_organic_keywords and semrush_subfolder_organic by specifying 'subdomain', though it does not explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings (e.g., semrush_domain_organic_keywords). No conditions, prerequisites, or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds no additional behavioral context (e.g., data freshness, pagination), but does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but under-specified. It could be expanded to include more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and 3 undocumented parameters, the description is inadequate. It neither describes what the tool returns nor provides enough context for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation for any of the three parameters (subfolder, database, limit). The description fails to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get paid keywords for a subfolder' uses a specific verb ('Get') and resource ('paid keywords for a subfolder'), making the purpose clear. However, it does not differentiate from sibling tools like 'semrush_subfolder_adwords_unique' or 'semrush_subdomain_adwords'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, nor any context about prerequisites or limitations. The description is purely functional with no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds 'requires .Trends' but does not disclose any other behavioral traits such as rate limits, data freshness, output format, or side effects. It neither contradicts nor significantly enhances the annotation-provided information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no waste. It efficiently conveys the core purpose and a key requirement. However, it is extremely brief and could be restructured to include additional necessary information without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and many sibling tools, the description is too sparse. It does not explain the return value, how to interpret results, or how to use optional parameters effectively. A more complete description would cover these aspects to help the agent invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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. It only implies the meaning of 'target' as a domain but provides no details on optional parameters (country, device_type, display_date, limit), their formats, or default behaviors. This gives minimal added value beyond the schema structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'geographic distribution of traffic for a domain', which defines the tool's primary action and object. It also mentions the '.Trends' requirement. However, it does not differentiate itself from sibling traffic tools (e.g., semrush_traffic_destinations, semrush_traffic_sources), so it lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only provides a prerequisite ('.Trends') but offers no guidance on when to use this tool versus alternatives (e.g., other traffic tools). There is no mention of specific use cases, exclusions, or scenarios where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. Description adds the subscription requirement (.Trends) which is useful behavioral context but does not disclose other traits like data freshness or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence with no waste. However, the brevity sacrifices necessary detail, making it less effective at conveying all required information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, no output schema, and many sibling tools, the description is too sparse. It fails to explain return format, parameter roles, or distinguish from related tools, leaving agents without enough context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of any parameters. The agent has only parameter names and types, with no added meaning for fields like country, device_type, display_date, or limit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves social media traffic distribution for a domain, using a specific verb and resource. It differentiates from sibling traffic tools (e.g., traffic_sources, traffic_geo) though could be more explicit about the output scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions a prerequisite (requires .Trends) but provides no guidance on when to use this tool versus alternatives like semrush_traffic_sources or semrush_traffic_geo. No when-not-to-use or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the '.Trends' requirement, which is a behavioral constraint beyond the annotations (readOnly, idempotent). However, it does not disclose other behaviors like rate limits, error cases, or what happens with invalid targets. Given annotations already cover safety, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence starting with the verb 'Get,' making it front-loaded and efficient. However, it may be too terse given the lack of parameter documentation, but conciseness itself is a strength.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters (including an enum) and no output schema, the description is far from complete. It does not explain the output format, how parameters affect results, or any constraints. The agent would struggle to use this tool effectively without external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (no parameter descriptions in schema), yet the description provides no explanation of any parameter. The agent must infer meaning solely from parameter names and schema types, which is insufficient for correct invocation, especially for optional parameters like 'display_date' and 'limit'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves subdomain traffic distribution for a domain, distinguishing it from other traffic tools (e.g., semrush_traffic_sources) by focusing on subdomains. However, it does not specify the exact output format or differentiate from very similar tools like semrush_subdomain_* siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks guidance on when to use this tool versus alternatives. It does not mention use cases, prerequisites beyond the '.Trends' requirement, or scenarios where a different tool might be better. No exclusions or contextual hints are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, and idempotentHint, so the safety profile is clear. The description adds one behavioral trait: the subscription requirement ('.Trends'). However, it omits other traits like rate limits, data freshness, or output format, which would be valuable for a tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at 9 words, front-loading the action. However, it is arguably too terse, sacrificing important details for brevity. Every word earns its place, but the description could be expanded without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, 5 parameters with 0% description coverage, and no explanation of output, the description is incomplete. It fails to explain what 'traffic distribution' means, how parameters affect results, or what the return data looks like. The subscription note is helpful but insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no information about any of the five parameters (target, country, device_type, display_date, limit). The description only mentions 'domain' implicitly through context. This is a major omission, leaving the agent to guess parameter formats and constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Get') and resource ('subfolder traffic distribution for a domain'). The mention of 'requires .Trends' adds a constraint. However, it does not explicitly differentiate from sibling tools like semrush_subfolder_organic or semrush_subfolder_rank, which are similarly named but different in focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The only usage hint is the subscription requirement, but no explanation of when traffic distribution is appropriate compared to other subfolder tools. Missing explicit when-to-use or when-not-to-use advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds no further behavioral details (e.g., data freshness, pagination, authorization needs). It only clarifies the TLD scope, which is beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it omits essential information about parameters and behavior. It is not front-loaded with the most critical details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With three parameters, no output schema, and the complexity of backlinks data, the description is severely lacking. It does not mention return format, pagination, or how the tool interacts with sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fails to explain any parameter. It does not clarify the meaning of 'target', 'target_type', or 'limit', leaving the agent to infer from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and clearly identifies the resource ('referring domains by TLD'), which distinguishes it from sibling tools like semrush_backlinks (general) and semrush_backlinks_anchors (anchor-specific).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not provide context such as 'use this for TLD-level breakdown' or exclude cases where other backlinks tools are more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds minimal behavioral context beyond stating it retrieves unique ads. It does not disclose rate limits, authentication needs, response format, or error conditions, which would be valuable beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no extraneous words. However, it may be too brief, sacrificing detail for brevity. It is appropriately front-loaded but could benefit from more context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, and the description does not mention what the tool returns (e.g., list of ads with metrics). For a tool with many siblings and no explicit return format, the description is incomplete for an agent to fully understand invocation results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of the three parameters (domain, database, limit). The description does not clarify what values are valid or the effect of each parameter, leaving the agent with only the schema structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'unique shopping ads', and the scope 'for a domain'. It differentiates from the sibling 'semrush_domain_shopping' by including 'unique', making the purpose specific and distinguishable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not state when to use this tool versus alternatives, nor does it give any context about prerequisites or when not to use it. Given the many sibling tools, this is a significant gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description adds minimal behavioral context. It does not describe what details are returned or any constraints beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence of 7 words with no fluff. It is very concise, though it could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should at least hint at the return structure (e.g., 'returns project name, status, settings'). It does not, leaving the output unspecified. For a simple tool, this is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the meaning of the only parameter (project_id), and the input schema has 0% description coverage. The agent receives no semantic help beyond the raw schema definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'details of a specific Semrush project', which distinguishes it from sibling tools like semrush_list_projects (list all) and semrush_create_project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., semrush_list_projects for listing all projects, semrush_update_project for updating). No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds no further behavioral details, but the annotations suffice for basic transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise. However, it is too minimal and could be expanded to include more useful information without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and many sibling tools, the description is insufficient. It does not explain what 'overview data' includes (e.g., metrics, time frame), making it hard for an agent to determine if this tool meets its needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameter meaning or format. While parameter names are slightly informative, the description fails to add value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves overview data for a specific keyword, but it does not differentiate from siblings like semrush_keyword_overview_single_db or semrush_batch_keyword_overview, which have similar purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. With many sibling tools focusing on keywords, a user would benefit from explicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds that it consumes '10 API units per line', which is a useful cost insight. However, it does not disclose return format, rate limits, or other behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence and very concise, but it omits essential details. It front-loads the purpose and cost but lacks parameter explanations and usage context, making it under-informative for its brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and sparse annotations, the description should compensate but fails to explain what 'detailed overview data' includes, how to format parameters, or what the response looks like. Sibling tools like semrush_keyword_overview exist, but the description does not help differentiate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no parameter descriptions), and the description provides only minimal context: it mentions 'keyword' and 'database' implicitly but does not explain accepted formats, allowed values (e.g., database codes), or the optional 'limit' parameter's meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get detailed overview data'), the resource ('a keyword'), and the scope ('from a specific database'). The name 'single_db' further distinguishes it from sibling tools like semrush_keyword_overview, though the description does not explicitly mention this distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., semrush_keyword_overview, semrush_batch_keyword_overview). The description implies usage for single-database keyword overviews but lacks explicit context about when to prefer it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is read-only and idempotent, so the description adds value by mentioning the cost of 40 API units per line. However, it does not disclose other behaviors such as pagination, rate limits, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but perhaps too terse. It front-loads the action but lacks structure to guide the agent on usage without additional details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no parameter descriptions, the description is insufficient for the agent to fully understand the tool's behavior, input constraints, or return format. The cost hint is helpful but not enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should compensate but only hints at the 'keyword' parameter via 'related to a term'. It does not explain the 'database' or 'limit' parameters, leaving the agent to infer from context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves 'question-based keywords' related to a term, which is specific and distinguishes it from sibling tools like 'related_keywords' that may return non-question keywords. However, it could be more explicit about the exact resource being queryed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'semrush_related_keywords' or 'semrush_keyword_overview'. No context on prerequisites or typical use cases is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds no additional behavioral context (e.g., response size, pagination, or data scope).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. However, it is perhaps too terse for the information needed, but conciseness is otherwise good.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, and the description does not hint at what data is returned. Combined with missing parameter context, the description is incomplete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate but fails entirely. It does not explain what project_id or snapshot_id represent or how to obtain them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get detailed site audit snapshot data' uses a specific verb and resource, clearly distinguishing it from sibling tools like semrush_site_audit_snapshots (which likely lists snapshots) and other audit tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., obtaining snapshot_id from semrush_site_audit_snapshots first). No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, destructiveHint, and idempotentHint, which cover the safety profile. The description adds no extra behavioral context (e.g., rate limits, authentication, output behavior) beyond what the annotations imply, so it does not significantly add value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, making it concise but lacking structure. It could be expanded to include key details like parameter usage or output format without becoming verbose, so it earns a middling score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (3 parameters, no output schema, many sibling tools), the description is too minimal. It does not explain what 'ranking data' means, the output structure, or how to effectively use parameters like database and limit. The agent lacks sufficient context to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the meaning or expected values for parameters (subdomain, database, limit). For example, 'database' has a default but no list of valid databases, and 'limit' lacks context on what it limits (e.g., results count). The description fails to compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get ranking data for a subdomain in a specific database', which is a clear verb+resource. However, it does not differentiate from similar sibling tools like semrush_subdomain_organic or semrush_subdomain_ranks, so the purpose is clear but not distinct enough for an agent to choose correctly among alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings. The description does not mention any exclusions, prerequisites, or scenarios, leaving the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, destructive, and idempotent hints. The description adds the .Trends prerequisite but does not mention other behaviors like data freshness, pagination, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, but it sacrifices informativeness for brevity. It does not fully earn its place by adding significant value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, no output schema, and no schema descriptions, the description is incomplete. It does not inform the agent about return values, default behaviors, or parameter usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the 5 parameters (target, country, device_type, display_date, limit). The agent gets no help beyond the schema structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'top pages by traffic', and adds the condition 'requires .Trends'. It distinguishes from sibling tools like semrush_domain_organic_keywords, but could specify traffic type (organic/paid).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only mentions a subscription requirement (.Trends) but provides no guidance on when to use this tool versus alternatives, such as traffic subdomains or sources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds no additional details about rate limits, authentication, or data freshness. Minimal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no unnecessary words. Highly concise and front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with simple parameters and good annotations, the description is minimally complete. However, it omits details about the output structure and does not mention the limit parameter, leaving some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain the 'limit' parameter or its role, nor does it clarify the format or scope of 'ranking data'. Fails to compensate for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets ranking data for a URL across all databases. However, it does not differentiate from sibling tools like semrush_url_rank or semrush_url_rank_history, which may have similar purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description lacks explicit context or exclusions, leaving the agent without criteria for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds the .Trends requirement, which is useful behavioral context, but otherwise lacks details on return format, pagination, or limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words, but it sacrifices necessary detail about parameters and usage. It is appropriately sized for the purpose clarity part but incomplete for a tool with undocumented parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of three parameters, no output schema, and zero parameter documentation, the description fails to provide enough context for an agent to use the tool correctly. It does not explain required parameter structure or expected results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the three parameters (targets, selected_targets, limit). The agent is left to infer meaning from names alone, which is insufficient for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' and identifies the resource as 'audience overlap and similarity data between domains', making the tool's purpose clear and distinct from siblings like semrush_audience_interests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only mentions a prerequisite ('.Trends') but provides no guidance on when to use this tool versus alternatives like semrush_audience_interests or other domain analytics tools. No explicit when/when-not or usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the tool is understood as safe and idempotent. The description adds the time range constraint ('over last 12 months') but does not disclose other behavioral traits like return format or pagination. With annotations covering safety, the description adds minimal value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no wasted words. It is front-loaded and efficient, though could be expanded with more behavioral context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and minimal description, the tool lacks completeness. It does not explain what data is returned, how to interpret results, or when to prefer sibling tools. For a tool with only 3 params and annotations, more contextual detail would be expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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. It only explains the domain parameter implicitly through the description, but database and limit parameters are not explained. The description does not add syntax or allowed values beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves ads history for a domain over the last 12 months, which is a specific verb and resource. It distinguishes from sibling tools like semrush_domain_adwords_unique and semrush_keyword_ads_history by focusing on domain-level ad history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no when-not-to-use conditions, and no mention of prerequisites or limitations. It leaves the agent to infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, which cover safety and idempotency. The description adds no additional behavioral context (e.g., response format, pagination, rate limits), so it does not go beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded with the core purpose. However, it may be too terse, sacrificing completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters (1 required), no output schema, and a large sibling set, the description omits key details like what 'paid keywords' entails, the role of 'database', and how 'limit' works. This is insufficient for an agent to confidently invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions in the schema itself. The tool description does not explain any of the three parameters (domain, database, limit), leaving the agent to rely solely on parameter names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'paid keywords for a specific domain'. It distinguishes from organic or shopping siblings by specifying 'paid', but does not differentiate from closely related tools like 'semrush_domain_adwords_unique' or 'semrush_keyword_paid_results'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the many similar sibling tools (e.g., semrush_domain_organic_keywords, semrush_domain_adwords_unique). The agent is left to infer the distinction without explanation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive, idempotent. Description adds API cost, which is useful for rate limiting awareness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence. Could include more structure but no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, description omits return format and parameter details. Incomplete for a tool with 3 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 0% and description provides no parameter explanations. Parameters like 'database' and 'limit' lack clarity on format or valid values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Get domains in Google's paid search results for a keyword'. Distinguishes from siblings like semrush_keyword_organic_results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use vs alternatives. Only mentions API unit cost, but lacks context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the safe, read-only nature is clear. The description's 'Get' aligns with this but adds no further behavioral details (e.g., data freshness, rate limits, or what 'winners and losers' implies). Since annotations carry most of the burden, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but sacrifices necessary information about parameters. It is front-loaded with the purpose, but the brevity leaves gaps. It could include parameter hints without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple schema (2 params, no output schema), the description should still explain the inputs and what 'winners and losers' means in terms of ranking changes. It omits parameter descriptions and doesn't clarify what domain/context is needed (e.g., does it require a domain parameter? Not in schema). The tool is incomplete for confident use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 2 parameters ('database' with default 'us', 'limit') with 0% description coverage. The description does not mention either parameter, failing to add meaning beyond the schema. It should explain that 'database' is a country code and 'limit' controls the number of results.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get winners and losers — domains with biggest ranking changes'. It uses a specific verb ('Get') and resource ('winners and losers'/'domains with biggest ranking changes'), which distinguishes it from sibling tools that focus on different aspects like domain overview or rank history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like semrush_domain_rank or semrush_domain_rank_history. There is no mention of prerequisites, context, or scenarios where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show destructiveHint false, but description lacks details on side effects like whether launching multiple crawls is allowed, if it overwrites previous audits, or time expectations. No additional context provided beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single, concise sentence. It is front-loaded and efficient, though lacking detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of launching an audit and no output schema, the description is insufficient. It doesn't explain the return value, potential delays, or how to monitor progress with sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter project_id is not described. Schema coverage is 0%, but description adds no meaning (e.g., what project_id refers to or how to obtain it).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool launches a new site audit crawl for a project, using specific verb and resource. It distinguishes from sibling audit tools (history, info, issues, etc.).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. Does not mention prerequisites (e.g., project must exist) or when not to use (e.g., if an audit is already running).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description carries a reduced burden. However, it adds no extra behavioral context such as pagination, ordering, or error conditions. The simple verb 'List' implies a read-only operation, but no further detail is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, efficient and front-loaded. However, it is underspecified for a tool with 0% schema coverage and no output schema. While concise, it sacrifices essential detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only one parameter, no output schema, and many sibling tools, the description should provide more context about what 'snapshots' are and how the output can be used. The tool is simple, but the description leaves the agent guessing about the return format and usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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. It only mentions 'for a project' without explaining what project_id represents or its role in identifying the project. The parameter is required but its source or permissible values are unspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('site audit snapshots for a project'). It distinguishes from siblings like semrush_site_audit_history and semrush_site_audit_snapshot_detail, which handle different aspects of site audits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. Among many sibling tools (e.g., semrush_site_audit_history, semrush_site_audit_issues), there is no context for selection or prerequisites like requiring an existing project ID.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, which are consistent with the description. The description adds no further behavioral details such as rate limits, data freshness, or pagination beyond what annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It is efficient and front-loaded with the key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of three parameters, no output schema, and numerous sibling tools, the description is too minimal. It does not explain what 'ranking data' entails, how results are structured, or any usage constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain the meaning or format of parameters like subfolder, database, or limit. The schema provides basic constraints but no semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves ranking data for a subfolder in a specific database, providing a verb and resource. However, it does not explicitly differentiate from sibling tools like semrush_subdomain_rank or semrush_url_rank, though the name suggests the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like semrush_subdomain_rank or semrush_url_rank. There is no mention of prerequisites, context, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, and idempotentHint, so the safety profile is clear. The description adds no extra behavioral context (e.g., pagination, limit behavior, response structure). It meets the minimal bar but does not leverage the opportunity to add value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but too terse. It sacrifices necessary parameter and behavioral information. While front-loaded with the core purpose, it lacks completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low schema coverage (0%) and no output schema, the description should provide more context for correct invocation. It does not explain how to specify a subfolder (e.g., leading slash, relative path) or the effect of the limit parameter. Annotations cover safety but not usage nuance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain either parameter. 'subfolder' is not defined (format or type), and 'limit' is not mentioned. The description fails to compensate for the missing schema descriptions, leaving the agent without essential parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Get ranking data'), the resource ('for a subfolder'), and scope ('across all databases'). It effectively differentiates from siblings like semrush_subfolder_rank (likely per-database) by implying global aggregation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like semrush_subfolder_rank, semrush_subdomain_ranks, or semrush_url_ranks. The description does not mention prerequisites, context, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, which provide safety information. The description adds the requirement for '.Trends API access', a behavioral constraint. However, it does not disclose other behavioral traits like rate limits, response size, or whether the tool handles large domain lists efficiently.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. Every word is purposeful: 'Get traffic summary data for domains' states the operation, and '(requires .Trends API access)' adds a critical constraint. Ideal length for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should explain what 'traffic summary data' includes (e.g., metrics like visits, page views, etc.). It does not. With two parameters and one required, the description is minimal and incomplete for an agent to fully understand the tool's results. Annotations help with safety but not completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions in the schema. The tool description fails to explain what 'domains' or 'country' mean, nor does it provide format details or examples. For instance, 'country' defaults to 'us' but is not clarified. The description adds no value beyond the schema structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'traffic summary data for domains', indicating a read operation. However, it does not differentiate from sibling tools like semrush_traffic_accuracy or semrush_traffic_destinations, which also deal with traffic data. The mention of '.Trends API access' adds specificity but doesn't clarify what 'summary' entails vs other traffic tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as semrush_traffic_sources or semrush_traffic_subdomains. The description lacks context about usage scenarios, prerequisites (beyond API access), or exclusions, leaving the agent to infer appropriateness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, covering safety. The description adds 'historical' but does not disclose further behavioral traits like time range granularity, data source, or response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence with no wasted words. However, it could pack more information in the same length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so description should hint at return values (e.g., rank over time, dates). It does not. Parameter semantics are missing, and sibling differentiation is absent. Incomplete given the tool's complexity and number of siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must explain parameters. It does not mention the meaning of 'database' (likely country database) or 'limit'. The agent has no added value beyond schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Get') and resource ('historical ranking data for a specific URL'). It distinguishes from current rank tools by using 'historical', but could be more specific about what the data includes (e.g., positions over time).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus similar siblings like semrush_url_rank, semrush_subdomain_rank_history, or semrush_domain_rank_history. The agent receives no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, destructiveHint, idempotentHint) already indicate safe read-only behavior. Description adds organic search context but does not disclose additional traits like rate limits or data freshness. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded, no wasted words. Efficiently conveys core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no parameter descriptions. Description fails to explain result format or parameter details, leaving significant gaps for a tool with three unannotated parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It only implies the domain parameter but does not explain 'database' (country?) or 'limit' (number of competitors?). Agent lacks guidance on required parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get competitors for a specific domain in organic search,' distinguishing it from sibling tools like semrush_paid_competitors. However, it does not specify what type of competitors (e.g., top shared keywords) beyond the domain context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use or when not to use this tool. No mention of alternatives or exclusions. While sibling names imply differentiation, the description does not explicitly guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds the grouping behavior ('grouped by URL'), which is useful context beyond annotations, but does not disclose pagination, rate limits, or output format. With annotations covering safety, this is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence without fluff. However, it is extremely short and could be expanded to include parameter details without losing conciseness. It earns its place by stating the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters, no output schema, and low schema coverage. The description fails to explain what 'grouped by URL' means in terms of output structure, returns format, or data limits. For a domain-level analytics tool, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters. It only implicitly references 'domain'. No meaning is added for 'database' or 'limit' beyond schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get unique organic keywords grouped by URL for a domain' uses a specific verb and resource, and explicitly mentions grouping by URL, which distinguishes it from sibling tools like semrush_domain_organic_keywords that likely return keywords without URL grouping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The user is left to infer from the tool name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and idempotentHint=true, which the description does not contradict. The description adds the behavioral constraint 'requires .Trends', which is valuable but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded, containing no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters and no output schema, the description is severely incomplete. It does not explain output format, interpretation, or usage of parameters like device_type or limit, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description adds no meaning for any of the 5 parameters (e.g., target, country, device_type, display_date, limit). The only mention is 'target' implicitly via the parenthetical prerequisite.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'education level distribution of audience'. It also mentions a prerequisite 'requires .Trends', which distinguishes it from sibling tools that provide other distributions (e.g., income, occupation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It only mentions a prerequisite, but no exclusions or referrals to sibling tools for different use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the read-only nature is covered. The description adds the cost of 100 API units per line, which is useful behavioral info beyond annotations. However, it does not disclose other traits like rate limits or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence that includes the core action and cost. It is efficient with no wasted words, though it could benefit from slight restructuring to separate the action from cost.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters (2 required) and no output schema. The description does not explain expected return format, pagination, or how to interpret the results. For a data-retrieval tool, this leaves significant gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning no parameter descriptions in the schema. The description does not explain the meaning or format of keyword, database, or limit, failing to add any semantic value beyond the schema's type constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns domains that bid on a keyword within the last 12 months, using a specific verb 'Get' and resource 'domains that bid on a keyword'. It distinguishes from sibling tools like semrush_keyword_paid_results by specifying historical data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention when not to use it or suggest other tools for related queries, leaving the agent without clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, which cover safety and idempotency. The description adds no further behavioral details beyond 'Get historical ranking data', so it meets the baseline but does not enhance transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no unnecessary words. However, it is too sparse given the missing parameter information; conciseness should not sacrifice completeness. Still, it is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With three parameters, no output schema, and 0% schema description coverage, the description does not adequately cover what the tool returns or how parameters affect results. The agent lacks context about the format of historical data, date range, or default behavior, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the JSON schema provides no descriptions for parameters. The tool description also fails to explain the meaning of 'subdomain', 'database', or 'limit'. Without any parameter semantics in either place, the agent must guess, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get historical ranking data for a subdomain' clearly states the action (get) and the resource (historical ranking data for a subdomain). The word 'historical' differentiates this from sibling tools like 'semrush_subdomain_rank' which likely returns current rank, making the purpose distinct and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'semrush_subdomain_rank' or 'semrush_subdomain_ranks'. The description does not mention prerequisites, limitations, or context for usage, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, providing safety profile. The description adds no additional behavioral context beyond what annotations provide. It does not disclose return format, pagination, or what 'ranking data' entails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous information, achieving maximum conciseness for its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 parameters, no output schema, and many siblings, the description is too brief. It does not indicate that the tool returns a list of ranks per database, nor does it clarify the format or expected output, leaving the agent with incomplete context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate. It mentions 'subdomain' but does not explain its format or provide examples, and the 'limit' parameter is completely ignored. The parameter names are somewhat self-explanatory but insufficient for precise usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and resource 'ranking data for a subdomain' and notes 'across all databases', indicating it returns multiple rankings. However, it does not distinguish itself clearly from similar sibling tools like 'semrush_subdomain_rank' which likely returns a single rank.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'semrush_subdomain_rank' or 'semrush_domain_organic_keywords'. The agent must infer from the name and description, which is insufficient for proper selection among many similar sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, destructiveHint=false, idempotentHint=true) sufficiently convey non-destructive, idempotent behavior. The description adds no extra behavioral context (e.g., pagination, rate limits, data scope), but the annotations already provide safety guarantees.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no fluff. Every word serves a purpose. However, conciseness is not a substitute for completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no output schema, and numerous sibling tools, the description lacks details on output format, pagination, and differentiation from similar tools. Requires more context for effective agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning the description does not explain any parameter. Only the 'subfolder' parameter is hinted via example. 'database' and 'limit' are undocumented, which is insufficient for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves organic keywords for a subfolder, with an example. It distinguishes from sibling tools like semrush_subdomain_organic by specifying 'subfolder' and 'organic', but does not explicitly differentiate from semrush_subfolder_organic_unique or paid variants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., semrush_domain_organic_keywords for root domain). No mention of prerequisites or contexts where this tool is inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive, which covers basic behavioral safety. The description adds the noteworthy constraint that .Trends API access is required, which is a key limitation. However, it does not mention data freshness, pagination, or any side effects beyond the annotation hints, so transparency is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that directly states the tool's function and a key requirement. It front-loads the purpose without extraneous words, making it easy for an agent to parse quickly. This is an ideal level of conciseness for a straightforward read tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having good annotations, the tool has no output schema and minimal parameter documentation. The description fails to explain what kind of data 'traffic sources' includes (e.g., direct, referral, search) or how the output is structured. An agent needs more context to correctly interpret results, especially since sibling tools exist for similar but distinct traffic metrics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must clarify parameter meanings. It adds no explanation for 'domain' (obvious from context) or 'country' (ambiguous – likely country code but not stated). The agent must infer that 'country' defaults to 'us' and likely expects a two-letter code, but the description provides no such elaboration, limiting its value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Get') and resource ('traffic sources data for a domain'), making the tool's purpose immediately understandable. Although it does not explicitly differentiate from many similar sibling tools (e.g., semrush_traffic_summary), the mention of 'traffic sources' provides enough specificity for an agent to select it for that particular data type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like semrush_traffic_summary or semrush_traffic_geo. The only contextual note is the requirement for .Trends API access, which is a prerequisite rather than a usage guideline. An agent lacks criteria to choose this over other traffic tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, indicating a safe read operation. The description adds no behavioral context beyond what's in the annotations, such as pagination or rate limits. It neither contradicts nor significantly supplements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, making it concise. However, it may be too minimal; additional context could be provided without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters, zero schema coverage, and many sibling tools, the description is insufficient. It lacks return value details, parameter explanations, and selection criteria, making it incomplete for an agent to use confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description fails to explain any parameter (url, database, limit) beyond implying url is the target. No format, defaults, or constraints are described, leaving the agent to guess.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get paid keywords for a specific URL', using a specific verb and resource. Among siblings, this tool is distinguished by targeting a URL rather than domain or subfolder, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like semrush_domain_paid_keywords or semrush_keyword_paid_results. The description only specifies the input is a URL, without any context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds no additional behavioral context (e.g., what 'paid search competitors' entails, data freshness, pagination). It neither contradicts nor enriches annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it under-specifies the tool. While not verbose, it sacrifices completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 parameters, no output schema, and no parameter descriptions, the description is insufficient for an agent to fully understand the tool's behavior. Key details like parameter format or result structure are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no explanation of parameters like 'database' (default value 'us') or 'limit'. Only 'domain' is inferable from context. Description fails to compensate for lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'paid search competitors for a domain'. This distinguishes it from sibling tools like 'semrush_competitors' (likely organic) and 'semrush_domain_paid_keywords' (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention when not to use it or provide context for selection among many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, establishing the tool as a safe read operation. The description adds the behavioral note about requiring '.Trends', which is useful context beyond annotations. However, it does not describe output format, pagination, or other behavioral traits, so value added is limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action. It is not verbose, but it omits critical parameter details, which could be added without sacrificing conciseness. It earns its keep by stating the prerequisite.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters with 0% schema description coverage and no output schema, the description is too sparse. It lacks information on parameter format, valid values, and expected return structure, making it difficult for an agent to use correctly. Annotations provide safety context, but completeness is low.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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 for parameter meaning. The description only implies 'target' is a domain but provides no explanation for 'country', 'device_type', 'display_date', or 'limit'. Without schema descriptions or additional context, the agent has insufficient semantic understanding to correctly invoke parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and resource 'outbound traffic destinations', clarifying the tool's function. It includes a prerequisite ('requires .Trends'), which adds clarity. However, it does not explicitly differentiate from sibling tools with similar names like traffic_sources or traffic_geo, though the term 'destinations' provides some distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the requirement '.Trends', indicating a condition for use. However, it does not provide guidance on when to use this tool versus alternatives among the many sibling traffic tools (e.g., traffic_sources, traffic_summary), leaving the agent to infer based on the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so safety is covered. The description adds minimal behavioral context ('based on backlinks') but does not explain what the categories represent, how results are aggregated, or any limitations. With annotations present, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but insufficiently informative for a tool with three parameters and zero schema descriptions. Important details are omitted, making it under-specified rather than efficiently concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters, no output schema, and 0% schema description coverage, the description fails to provide adequate context. It does not explain the return format, how categories are derived, or how parameters like 'limit' and 'target_type' affect the output. The presence of many sibling tools further necessitates more context, which is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description offers no explanation of the three parameters (target, target_type, limit). The description does not clarify the role of 'target_type' (enum: root_domain, domain, url) or how 'limit' affects the results. The lack of parameter documentation forces the agent to infer meaning from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), resource ('domain categories'), and scope ('for a target based on backlinks'). It distinguishes this tool from sibling tools like semrush_backlinks (generic backlinks data) and semrush_backlinks_anchors (anchor-specific data).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or when not to use this tool. The context is implied (obtain domain categories from backlinks), but alternatives are not mentioned. The description provides no exclusionary criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to repeat safety. However, the description adds no additional behavioral context (e.g., response format, rate limiting). With annotations, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple query tool with two parameters and no output schema, the description is partially complete. It identifies the core function but omits parameter formats and output hints, leaving gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description only mentions 'for a specific domain or URL' without clarifying the target format (e.g., bare domain vs full URL) or explaining the limit parameter. This fails to compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves referring domains for a specified domain or URL, using a specific verb and resource. It distinguishes itself from siblings like semrush_backlinks or semrush_backlinks_anchors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as semrush_backlinks or semrush_backlinks_pages. No mention of prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the agent knows it is a safe read operation. The description adds no additional behavioral context (e.g., authentication, rate limits, or output format). It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at 7 words and quickly conveys the core purpose. It could be slightly more informative without becoming verbose, but it is not overly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a keyword research tool with 3 parameters and no output schema, the description is too minimal. It does not define 'related keywords', describe the output structure, or mention any limitations (e.g., language or region). The annotations cover safety but not semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the schema provides no parameter descriptions. The tool description does not explain the meaning of 'keyword', 'database', or 'limit', nor does it clarify default values or constraints beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('related keywords for a specific keyword'). It distinguishes this tool from siblings like semrush_broad_match_keywords or semrush_phrase_questions by specifying 'related keywords'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention when to prefer related keywords over broad match or other keyword tools, nor does it indicate prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds little beyond stating it retrieves data, which is consistent. No contradictions, but no additional behavioral context like rate limits or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the core action. It wastes no words, though it could benefit from a slightly more structured format (e.g., listing key capabilities).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (2 params, no output schema), the description is too minimal. It does not specify what the returned data includes, leaving the agent without understanding the output format or contents. A brief list of examples would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the meaning of 'project_id' or 'page_id', leaving the agent to infer from context. With 0% schema description coverage, the description fails to compensate, providing no clarity on what these parameters represent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves 'detailed audit data for a specific page,' using a specific verb and resource. It effectively distinguishes itself from sibling tools like 'semrush_site_audit_pages' (list pages) and 'semrush_site_audit_issues' (get issues).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as when to use 'semrush_site_audit_pages' or 'semrush_site_audit_snapshot_detail'. There is no mention of prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, establishing this as a safe read operation. The description adds the adjective 'historical' but does not disclose additional behaviors such as date range limitations, pagination, or any rate limits. Since annotations carry the safety burden, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 6-word sentence with no wasted words. However, it is arguably too concise for a tool with multiple parameters and many siblings. A slightly longer description with parameter hints would not harm conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite many sibling tools, no output schema, and 3 parameters, the description provides minimal context. It does not explain what historical ranking data includes (e.g., time range, metrics), how to interpret results, or any prerequisites. The tool feels incomplete for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate by explaining parameters, but it adds no information beyond parameter names and types. The agent is left guessing the meaning of 'database' (country code) and 'limit' (max results). This is a significant gap given the minimal schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'historical ranking data', and the scope 'for a subfolder'. It effectively differentiates from sibling tools like semrush_subfolder_rank (current data) and semrush_subfolder_ranks (likely multiple ranks) by specifying 'historical'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. With many sibling tools for subfolder data (rank, ranks, organic, etc.), the agent receives no context on when historical data is appropriate or how it differs from current data. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool is read-only, non-destructive, and idempotent. The description adds valuable cost information (10 API units per line), which is beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence that is front-loaded with the core action. No unnecessary words or structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and three parameters lacking explanation, the description is incomplete. It omits details about pagination, result structure, and how the limit parameter works.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the three parameters (keyword, database, limit). It fails to compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it gets domains ranking in Google's top 100 for a keyword, using a specific verb and resource. It distinguishes from sibling tools like semrush_keyword_paid_results and semrush_keyword_overview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, or when not to use it. The description is brief and lacks context about typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, and idempotentHint, so the description does not need to repeat them. It adds no additional behavioral context beyond the grouping by URL, which is already implied by the tool name. Adequate but not enhanced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that conveys the core purpose without wasted words. It earns its place by being direct and focused.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no output schema, and many siblings, the description lacks completeness. It does not explain the output format, the meaning of 'unique' in grouping, or how the limit parameter affects results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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. It only implicitly references 'subfolder' and does not explain 'database' or 'limit'. The parameter names are somewhat self-explanatory, but the description adds no value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves unique organic keywords grouped by URL for a subfolder, using a specific verb and resource. It effectively distinguishes from sibling tools like 'semrush_subfolder_organic' by specifying 'unique'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'semrush_subfolder_organic' or domain-level variants. No when-to-use or when-not-to-use information is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly, destructiveHint=false, and idempotentHint=true. The description adds the '.Trends' requirement, which is useful context not covered by annotations. However, it does not go beyond that to describe behavioral nuances.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundancy. It is front-loaded with the primary action and includes essential prerequisite information concisely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters, no output schema, and many siblings, the description is insufficient. It does not explain parameter formats, default behavior, or the structure of the accuracy score result, leaving significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides no explanation of the three parameters: target, display_date, and limit. The description does not add any meaning beyond what the schema structure already conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'data accuracy score for traffic analytics', which is distinct from sibling tools like semrush_traffic_destinations or semrush_traffic_geo. The prerequisite note further specifies scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite ('.Trends'), providing some usage context, but does not explicitly state when to use this tool versus alternatives or when not to use it. No sibling differentiation is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, destructiveHint, and idempotentHint. The description adds '20 API units per line' as a cost hint, which is useful beyond annotations. However, it does not disclose other behaviors like pagination or data format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 12-word sentence, front-loaded with the action 'Get broad matches'. The cost note is efficiently parenthesized. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description lacks information on return format or fields. It adequately covers the basic intent but omits details about database selection and limit effects. Minimal for a tool of this simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
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. It only mentions 'keyword', failing to explain 'database' (required) or 'limit' (optional). This leaves significant gaps in parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get broad matches and alternate search queries for a keyword', specifying the verb, resource, and input. It distinguishes from siblings like semrush_related_keywords by focusing on broad matches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like semrush_related_keywords or semrush_keyword_overview. The description only states what it does, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with annotations (readOnlyHint=true, destructiveHint=false, idempotentHint=true) by stating 'Get', indicating a read operation. However, it adds no additional behavioral details such as data source freshness, rate limits, or result ordering. Given that annotations already cover the safety profile, the description is neutral but does not enhance transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, free of redundancy. It is concise and front-loaded. However, it could be slightly expanded to include key parameter context without losing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too sparse for the tool's complexity (3 params, no output schema, many siblings). It omits expected details such as return value structure, default limit, accepted database values, and any limitations. This leaves significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description bears full responsibility for explaining parameters, but it only mentions 'URL' implicitly. It fails to clarify meaning of 'database' (e.g., country code), 'limit' (e.g., max results), or constraints like minLength. This leaves the agent to infer or rely on external knowledge.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and clearly identifies the resource ('organic keywords for a specific URL'). It effectively distinguishes this tool from siblings like semrush_domain_organic_keywords (domain-level) and semrush_url_adwords (paid keywords), making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives is provided. While the purpose is clear, there is no mention of when not to use it (e.g., for domain-level queries) or which sibling to prefer. The usage is implied by the name and description, but explicit context is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive, and idempotent behavior. The description adds value by disclosing the API unit cost ('50 API units per line'), which is a relevant operational detail not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the core purpose and a key cost detail, with no unnecessary words. It is appropriately front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description should hint at what the tool returns (e.g., a numerical difficulty score, range, etc.). It does not, leaving the agent without critical context about the result format. Additionally, it does not clarify whether 'per line' means per keyword or per API call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the tool description does not explain the meaning or usage of the 'keywords' or 'database' parameters. For example, it does not specify that 'database' is a geographic code or how to format keywords. This forces the agent to rely solely on schema constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Get' and the resource 'difficulty index for ranking in Google's top 10', making the purpose specific and unambiguous. It effectively distinguishes from sibling tools like semrush_keyword_overview by focusing solely on the difficulty metric.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as semrush_keyword_overview or semrush_batch_keyword_overview. The description does not include any context for appropriate or inappropriate usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. Description adds useful information about API unit cost (10 per line), which is not in annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single clear sentence with no unnecessary words. Important information about keywords limit and database is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 0% schema coverage, the description is insufficient. It does not explain return values, error handling, or behavior for invalid inputs. For a batch tool, more detail is expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, with no parameter descriptions. Description mentions 'database' but does not explain its values, format, or the meaning of '10 API units per line' in relation to parameters. Fails to compensate for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Analyze', resource 'keywords', and scope 'up to 100 at once in a specific database'. It distinguishes from siblings like semrush_keyword_overview and semrush_keyword_overview_single_db.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use for batch keyword analysis but provides no explicit guidance on when to use versus single-keyword alternatives or when not to use. Lacks exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds no additional behavioral traits, so it meets the baseline set by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that states the tool's purpose with no wasted words. Perfectly concise for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no input and no output schema, the description is adequate but lacks details about the return structure (e.g., project IDs and names), which could be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the baseline is 4. The description adds no parameter information, but none is needed since there are no parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all Semrush projects' with a specific verb (List) and resource (projects), and effectively distinguishes from siblings like semrush_get_project and semrush_create_project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., semrush_get_project for a single project). Users must infer context from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral context beyond annotations by specifying the subscription requirement (.Trends) and platform limitation (desktop only). However, it does not discuss rate limits, data freshness, or output format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of 13 words that immediately conveys the core purpose. It contains no unnecessary information, making it highly efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema and four parameters (with zero schema description), the description does not cover what the tool returns (e.g., single value, time series) or explain parameters like 'display_date' and 'limit'. The lack of output details and parameter semantics leaves significant gaps for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions in the schema. The description fails to compensate by explaining any of the four parameters (target, country, display_date, limit) beyond implying 'target' is the domain. This leaves the agent without necessary usage details for parameters like 'country' or 'limit'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'purchase conversion rate', and the scope 'for a domain', distinguishing it from other domain metric tools like traffic or backlinks. The constraints (requires .Trends, desktop only) further clarify its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions prerequisites (requires .Trends, desktop only) but does not provide guidance on when to use this tool versus the many sibling tools for other domain metrics. No explicit when-to-use or when-not-to-use advice is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-readonly and non-destructive, consistent with 'Update'. No additional behavioral traits disclosed beyond the verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, succinct sentence with no extraneous information, appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with two clear parameters and no output schema, the description is mostly sufficient. Could mention that only the name is updated, but not critically missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should explain parameters. It only states 'project name' but does not clarify that project_id is the identifier and project_name is the new value, relying on schema default names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Update' and the target resource 'Semrush project name', distinguishing it from sibling tools like semrush_create_project or semrush_get_project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives, but the context is implied by the tool's function. No exclusions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds no extra behavioral context beyond the balance check. It does not disclose e.g., whether the call counts against usage limits or response format, so it barely adds value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous content. Every word is necessary and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (no parameters, no output schema), the description is fully complete. It suffices for an agent to understand the tool's function without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100%. The description adds no parameter details, which is acceptable since no parameters exist. Baseline score of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Check the remaining API units balance'. It uses a specific verb ('Check') and resource ('API units balance'), and is distinct from all sibling tools, which focus on other Semrush API features.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context without explicit when/when-not statements. Given the tool's simplicity (no parameters), the purpose is self-evident, and there are no similar alternatives among siblings, so the clarity is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![semrush-mcp MCP server](https://glama.ai/mcp/servers/mrkooblu/semrush-mcp/badges/card.svg)](https://glama.ai/mcp/servers/mrkooblu/semrush-mcp)

Score Badge

Copy to your README.md:

[![semrush-mcp MCP server](https://glama.ai/mcp/servers/mrkooblu/semrush-mcp/badges/score.svg)](https://glama.ai/mcp/servers/mrkooblu/semrush-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mrkooblu/semrush-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server