semrush_traffic_sources

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.

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.

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.

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.

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.

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.