The goals CONFIGURED on a site — what it measures, not how those goals performed. Use top_goals for conversion numbers. Response: {"goals":[{"id":7,"name":"Signup","event_name":"Signup"|null,"path":"/thanks"|null,"operator":"e|b|c","scroll_depth":N|null}]}.
| Name | Required | Description | Default |
|---|---|---|---|
| site | Yes | site_id from list_sites. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read operation, so the description does not need to repeat that. It adds value by explaining the semantic scope (configured goals, not performance) and providing the exact response shape, giving the agent expectations beyond the annotation.
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?
Two sentences, each earning its place: the first differentiates the tool from alternatives, the second gives the complete response shape. No filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 1-parameter, read-only list operation with no output schema, the description supplies the necessary return shape and disambiguates the semantics. Nothing essential is missing for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter has 100% schema description coverage ('site_id from list_sites'), so the schema carries the semantic load. The description adds only the general context that goals are configured 'on a site,' which aligns with the parameter but does not materially extend its meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('list') and resource ('goals CONFIGURED on a site'), and immediately clarifies what it does not do ('not how those goals performed'). This cleanly distinguishes it from top_goals without needing the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent when to use this tool versus an alternative: use top_goals for conversion numbers. The phrase 'what it measures, not how those goals performed' frames the appropriate use case clearly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Most tools map cleanly to distinct resources and actions: sites, goals, funnels, tracking settings, filters, and statistics. Some ambiguity exists between the generic query_stats and the many top_* / visitors_over_time convenience queries, but the descriptions mostly clarify when each should be used.
The CRUD tools consistently use create_, get_, list_, and update_ prefixes, but a sizable minority deviate: top_* forms a separate pattern, and current_visitors, funnel_report, and visitors_over_time are noun-phrase names rather than verb_noun.
25 tools sits at the heavy end for an analytics server. Many top_* tools overlap with what query_stats could do, making the count feel somewhat inflated, though the domain is broad enough that the number is not unreasonable.
The tool set covers site management, goals, funnels, tracking, filters, and statistics well. However, there are no delete operations for sites, goals, or funnels, leaving an obvious lifecycle gap and no way to clean up configured resources.
