BigQuery MCP Server

Server Quality Checklist

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

Latest release: v3.1.0
Disambiguation2/5
Many gsc_* tools have overlapping purposes, such as gsc_traffic_drops, gsc_content_decay, and gsc_alerts all addressing traffic declines, or gsc_ctr_opportunities and gsc_ctr_benchmark both focusing on CTR underperformance. The detailed descriptions help, but the sheer number of similar analytics tools creates ambiguity for an agent selecting the right one.
Naming Consistency3/5
All names use snake_case, which is consistent. However, the pattern is mixed: core BigQuery tools follow a verb_noun structure (list_datasets, describe_table), while the gsc_* and ga4_* tools use noun phrases with prefixes (gsc_quick_wins, ga4_gsc_revenue). This mixed convention is still readable but not uniformly predictable.
Tool Count2/5
With 32 tools, this server is over-scoped. The large block of gsc_* analytics tools (20+) significantly inflates the count beyond the 15-tool threshold for a well-scoped set. Even for an SEO analytics server, the count feels heavy, and for a general BigQuery server it is excessive.
Completeness4/5
The SEO analytics surface is remarkably comprehensive, covering snapshots, quick wins, CTR, content gaps, decay, cannibalisation, alerts, recommendations, forecasting, and GA4 integrations. The main gap is the lack of BigQuery write operations (create/update/delete), which may be acceptable for a read-only analytics server but is a notable omission for a general BigQuery tool.
Average 4.2/5 across 32 of 32 tools scored. Lowest: 3.5/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 3 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 Apache 2.0.
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

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. It clearly says the tool checks for and returns severity-rated alerts, and adds critical behavioral rules (only report data, don't speculate, present visually), which is useful. However, it does not address operational details such as permissions, rate limits, or whether the operation is read-only, so transparency is partial.
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 front-loaded with the core purpose and uses clear sections. The PRESENTATION block is lengthy and includes agent-facing style instructions that could be viewed as beyond the tool's core description, but every section serves a distinct purpose, so it remains appropriately structured.
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?
Given the lack of output schema and annotations, the description provides a good level of context: alert categories, severity ratings, how to handle data gaps, and presentation expectations. It does not specify exact response fields, but for an alert tool this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all five parameters with descriptions. The tool description adds context about alert types and severity but does not add new parameter-specific meaning; the baseline 3 is appropriate.
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 'Check' with a clear resource ('SEO alerts') and enumerates concrete alert types (position drops, CTR collapses, click losses, disappeared pages), making its function clear. However, it does not explicitly distinguish itself from sibling tools like gsc_traffic_drops or gsc_anomalies, so it stops short of full 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool—when the user needs a prioritized list of SEO alerts—but it does not state explicit alternatives or exclusions. No guidance on choosing this over gsc_traffic_drops or gsc_anomalies is provided; the 'when to use' is inferred from the purpose rather than stated.
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?
With no annotations, the description carries the transparency burden. It lists return contents but does not explicitly state that the operation is read-only, side-effect-free, or describe permission requirements. The verb 'Get' implies safety, but this is not made explicit.
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 that efficiently conveys the purpose and key details with no irrelevant content. It earns its place without redundancy.
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 tool with no output schema, the description sufficiently communicates what the tool returns and its scope. It does not cover edge cases or prerequisites, but given the schema clarity and tool purpose, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all parameters with 100% description coverage. The tool description does not add significant meaning beyond the schema, though it reinforces that the table is a 'specific BigQuery table' and that schema details are returned.
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 function: 'Get detailed schema information for a specific BigQuery table' and enumerates specific return details (column names, types, descriptions, row count, size, partitioning, clustering). This distinguishes it from siblings like list_tables or sample_rows.
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 implies when to use the tool (when schema details are needed) but does not explicitly provide when-to-use vs alternatives or exclusions. It is clear enough for basic inference but lacks explicit guidance.
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?
No annotations are provided, so the description carries the full burden. It adds critical behavioral guidance: 'Base your analysis ONLY on the data returned', 'Do not speculate about causes', and mandates a rich visual presentation via artifacts. This goes beyond schema and helps the agent handle output responsibly, though it does not disclose internal details like data freshness or limitations of URL pattern matching.
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 long paragraph with multiple sections (purpose, IMPORTANT, PRESENTATION). It is front-loaded with the core purpose, but the extensive behavioral and presentation instructions make it longer than necessary for a tool definition. Each section is relevant, but it could be more concise.
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 tool with 3 params and no output schema, the description covers purpose, input (url_pattern), and output metrics. It also provides analysis and presentation guidelines. It lacks a precise definition of 'group of pages' and doesn't explain the return structure, but overall it is sufficiently complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema documents all three parameters with 100% coverage. The description adds minimal extra meaning beyond clarifying that url_pattern matches a URL path pattern, which is already in the schema. No new semantics for days or dataset are provided.
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 what the tool does: 'See how a group of pages performs as a whole. Aggregates clicks, impressions, CTR, and position for all pages matching a URL path pattern, plus top pages and queries.' It specifies the verb, resource, metrics, and scope, distinguishing it from sibling tools like gsc_site_snapshot or gsc_cannibalisation.
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 implies a use case ('See how a group of pages performs as a whole') but does not explicitly state when to use it vs alternatives or mention exclusions. It lacks contrast with sibling tools such as gsc_site_snapshot or gsc_content_gaps, which could overlap in purpose.
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?
With no annotations, the description carries the full burden of behavioral disclosure. It provides substantial guidance: 'Base your analysis ONLY on the data returned', 'Do not speculate about causes', and detailed presentation requirements (artifacts, summary cards, colour-coded indicators). These go beyond the schema and inform the agent about analytical boundaries and output format. However, it does not disclose potential error cases or data limitations beyond the instruction to say when information is insufficient.
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 well-structured with clear sections: purpose, IMPORTANT analytical constraints, and PRESENTATION guidelines. While somewhat lengthy, each sentence contributes useful information for proper tool usage. The use of labels ('IMPORTANT', 'PRESENTATION') enhances scannability, though it could be trimmed slightly without losing value.
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?
The description covers the tool's purpose, analysis constraints, and presentation expectations, which is substantial given the absence of an output schema. It also ensures the agent knows how to handle insufficient data. However, it lacks specifics on the data returned (e.g., exact metrics or verdict thresholds), but the presentation requirements imply a rich visual output. Overall, it is complete enough for effective invocation and result interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema documents all three parameters (days, dataset, min_impressions). The tool description does not add parameter-specific information, but per the rubric, the baseline is 3 when schema coverage is high. No additional semantic value is expected, and the description does not need to compensate.
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 function: 'Compare your actual CTR per page against industry benchmarks by position' and 'Flags pages significantly underperforming for their ranking position with verdicts.' This is a specific verb+resource+scope that distinguishes it from sibling tools like gsc_ctr_opportunities or gsc_quick_wins, which likely focus on different aspects of CTR analysis.
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 implies usage context (benchmarking CTR by position) but does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or alternatives. The purpose is clear enough to infer when it is appropriate, but explicit guidance is missing.
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?
With no annotations, the description carries the full burden. It discloses important behavioral expectations for the agent, such as 'Base your analysis ONLY on the data returned,' 'Report exact numbers,' and 'Do not speculate about causes.' However, it does not describe the tool's own operational traits (e.g., read-only nature, output fields, or potential limitations like pagination). The focus is on agent conduct rather than tool 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 longer than minimal but well-structured, with a clear purpose statement, an 'IMPORTANT' section for analysis rules, and a 'PRESENTATION' section for output requirements. While verbose, each section serves a distinct purpose, and it is front-loaded with the essential purpose. It could be slightly more concise, but the instructions are value-adding.
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?
Despite having no output schema, the description compensates by providing thorough guidance on how to handle and present results. It implies the data includes metrics like severity and change direction through the presentation instructions. However, it does not explicitly list the returned fields (e.g., impressions, clicks, position), leaving some ambiguity about the exact data structure. Overall, it covers purpose, usage, analysis constraints, and presentation, making it fairly complete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% description coverage for all four parameters, so the baseline is 3. The description adds some context by indirectly referencing 'recent data' and 'baseline period' which map to recent_days and baseline_days, but it does not add new meaning beyond the schema or clarify parameter usage further.
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 function: 'Discover queries that appeared in your recent data but were not present in the baseline period.' This is a specific verb (Discover) with a resource (queries) and a comparative scope, which distinguishes it from sibling tools like gsc_content_gaps or gsc_quick_wins that likely focus on different patterns.
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 provides clear use cases: 'spotting new ranking opportunities, trending topics, or the impact of recently published content.' It gives context on when to use the tool but does not explicitly compare with alternatives or state exclusions, so it falls short of a 5.
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?
The description provides strong behavioral guidance: instructs to base analysis only on returned data, report exact numbers, avoid speculation, and state when data is insufficient. With no annotations provided, this is essential context. It also specifies the presentation style using artifacts and dashboard-like formatting.
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 front-loaded with the core purpose, followed by necessary constraints and presentation requirements. The PRESENTATION section is detailed but justified for a report tool. It is somewhat long but every sentence serves a purpose and is well structured.
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?
The tool has no output schema, so the description makes the return format clear as markdown. It covers the report composition, data fidelity rules, and presentation expectations, which is sufficient for an agent to understand how to handle the result. The only minor gap is explicit connection to sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptions for all three parameters, giving 100% coverage. The tool description repeats the section names already found in the include_sections parameter description, adding no new semantic value. The days and dataset parameters are only documented 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 'Generate a comprehensive markdown performance report' and enumerates all covered sections (site snapshot, alerts, quick wins, traffic drops, content decay, recommendations). This distinguishes it from sibling tools that focus on individual areas like gsc_quick_wins or gsc_site_snapshot.
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?
Usage is implied through the list of sections, but there is no explicit guidance about when to use this comprehensive tool versus the individual sibling tools. No alternatives are named or exclusions provided, so the agent must infer the appropriate context.
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?
With no annotations, the description carries the full burden. It explicitly instructs the agent to base analysis only on returned data, report exact numbers, avoid speculation, and admit insufficient information—providing strong behavioral context. It also mandates a rich interactive presentation format. It does not mention internal side effects, but 'returns' implies a read-only operation, and the presentation rules are clearly disclosed.
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 longer than average but well-structured into three sections: overview, IMPORTANT analysis rules, and PRESENTATION requirements. Each sentence adds value, with the purpose front-loaded. The length is justified by the need to convey both data handling rules and output formatting expectations.
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?
Given the tool's simplicity (2 optional params, straightforward output) and no output schema, the description adequately covers return values (metrics list) and provides clear instructions for handling incomplete data. It lacks explicit edge-case behavior (e.g., empty dataset), but the 'say so clearly' instruction mitigates this. Overall, it is complete for its scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add significant parameter detail beyond the schema; it references 'prior period' (implying 'days') but does not explain the 'dataset' parameter or how they interact. The schema already describes both parameters adequately, so no compensation is needed.
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 a specific verb ('Get a quick overview') and resource ('how the site is performing'), and lists the exact metrics returned (clicks, impressions, CTR, position, unique pages, queries) plus the comparison to the prior period. This distinguishes it from the more specialized sibling tools like gsc_quick_wins or gsc_ctr_opportunities, which target specific aspects.
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 phrase 'quick overview' implies use for high-level summaries, and the mention of 'comparison to the prior period' gives context. However, there is no explicit guidance on when to choose this tool over alternatives like gsc_report or ga4_gsc_page_performance, nor any stated exclusions or prerequisites.
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?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It conveys a read-only, non-destructive listing operation, but doesn't explain response format, default project handling, or potential large result sets. For a simple list tool, the basic statement is somewhat transparent but lacks detail.
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 two short sentences with the action verb front-loaded ('List all datasets') and no filler. Every word earns its place.
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 discovery tool, the description plus schema provide adequate context: it states what it does and when to use it. It doesn't specify return structure, but since there's no output schema and it's a list operation, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the single optional project_id parameter with 100% coverage. The description adds no additional parameter semantics, so the baseline score of 3 is appropriate.
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 function with a specific verb and resource: 'List all datasets in the BigQuery project.' It also adds purpose by saying 'Use this first to discover what data is available,' distinguishing it from siblings like list_tables and describe_table.
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 gives explicit context: 'Use this first to discover what data is available.' This tells the agent when to invoke the tool. However, it doesn't mention exclusions or explicitly name alternatives like list_tables, so it lacks a when-not-to-use guideline.
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?
No annotations are provided, so the description carries the burden. It adds a behavioral detail ('Uses INFORMATION_SCHEMA for efficiency') and specifies output includes schemas. However, it does not disclose permissions, cost, pagination, or exact return format. For a simple read-only listing tool, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the primary function, an efficiency note, and a usage recommendation. No redundancy, front-loaded with the action.
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 2-parameter read-only tool with no output schema, the description covers the essential aspects: what it does, how it works internally, and when to use it. It does not detail return values, but the purpose implies a list of tables with schemas, making this adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with both parameters documented. The description does not add parameter-level detail, but the schema already provides complete semantics for dataset and project_id, warranting the baseline score.
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 all tables in a BigQuery dataset with their schemas.' It uses a specific verb and resource, and distinguishes from siblings like list_datasets and describe_table by focusing on tables with schemas.
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 provides clear usage context: 'Use this to understand what tables and columns are available before writing queries.' It does not explicitly mention alternatives or exclusions, but the context implicitly differentiates from query tools and describe_table.
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?
With no annotations, the description must carry the behavioral disclosure burden. It discloses a cost limit ('Limited to 1GB bytes billed') and implies read-only behavior via 'preview', but does not describe return format, sampling randomness, or pagination. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, with the primary purpose front-loaded, followed by a use case and a cost caveat. Every sentence adds value, and there is no redundancy or fluff.
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?
Given the tool's simplicity, a clear output schema, and full parameter descriptions in the schema, the description covers the essential aspects: what it does, when to use it, and a key limitation. It lacks an explicit mention of alternative tools, but the context is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific detail beyond what the schema already provides, but it does not need to compensate given the high schema coverage.
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 ('preview') and resource ('sample rows from a table'), clearly stating the tool's function. The phrase 'without writing SQL' distinguishes it from the sibling query tool, making the 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool ('quickly understanding what data looks like') and implies an alternative to writing SQL, but it does not explicitly name alternatives or state when not to use it. Thus it meets the 'clear context, no exclusions' level.
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?
No annotations are provided, so the description carries the full burden. It discloses important behavioral expectations: not speculating, reporting exact numbers, and presenting results as interactive visualizations. These add significant context beyond the tool name and schema. However, it doesn't detail return format or data source specifics, so it's not a 5.
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 front-loaded with the core purpose, then adds clear IMPORTANT and PRESENTATION sections. It is somewhat long but each section earns its place by guiding the agent's behavior. The structure makes it scannable, though the presentation instructions could be considered generic across GSC tools.
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?
There is no output schema, but the description mentions what the tool shows (competing pages, positions). It also instructs how to handle insufficient data. With 0 required parameters and a simple input schema, this is complete enough for an agent to invoke the tool properly, though more detail on the exact return structure would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters (days, dataset, min_impressions) have descriptions in the schema, so coverage is 100%. The tool description adds no additional meaning beyond what the schema already provides. Baseline 3 is appropriate since the schema does the heavy lifting.
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 with a specific verb ('Find') and resource ('keywords where multiple pages from your site compete'). It distinguishes itself from sibling tools by focusing on cannibalisation and ranking positions. This is exactly the level of specificity expected.
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 provides clear context on how to use the tool and what to do with the data ('Base your analysis ONLY on the data returned', 'Do not speculate'), but it does not explicitly mention when to choose this tool over alternatives, nor does it state exclusions. The distinct purpose is implied, so it's slightly above missing guidance 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosure. It transparently describes the tool's output (queries with impressions and poor ranking) and imposes explicit constraints on agent behavior (base analysis only on data, avoid speculation, admit insufficient data). It also mandates a rich interactive presentation, which goes beyond the bare data return. However, it omits operational details like authentication 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured into clear sections: purpose, analysis constraints, and presentation requirements. It is front-loaded with the core purpose. While the PRESENTATION section is lengthy, each sentence serves a functional purpose in guiding the agent's output, and the overall structure is organized and scannable.
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?
Given no output schema, the description does a good job of explaining the expected data (queries matching a condition) and sets comprehensive expectations for analysis and presentation. It covers the tool's logic and constraints, though it does not enumerate the exact output fields, which would be useful for complete clarity. For a tool with four optional parameters and no output schema, this is a solid and complete description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reinforces the semantic meaning of key parameters ('rank beyond position 20' for min_position, 'where you get impressions' for min_impressions) but does not add new syntax or examples beyond 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 opens with a specific verb and resource: 'Find topics you should create content for.' It clearly defines the tool's functionality by specifying the exact condition (impressions but rank beyond position 20), which distinguishes it from sibling tools like gsc_quick_wins or gsc_ctr_opportunities.
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 provides clear context for when to use the tool ('Find topics you should create content for') and gives detailed instructions on how to handle the results (analysis rules, presentation). It does not explicitly mention alternatives or exclusions, but the context is strong enough to guide appropriate use.
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?
With no annotations, the description carries the behavior burden and does so well. It explicitly states to base analysis only on returned data, report exact numbers, avoid speculation unsupported by data, and honestly state when information is insufficient. It also mandates a specific presentation format (rich interactive visualization with artifacts). This gives meaningful behavioral transparency beyond the basic read-only nature.
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 front-loads the core purpose in the first sentence, then separates analysis rules and presentation requirements into clearly labeled sections. While long, each section provides necessary behavioral guidance. It is somewhat verbose but every part adds practical value for correct usage.
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?
There is no output schema, so the description compensates by specifying how results should be presented and how the agent should reason about them. It clearly defines the analysis approach and output format. It could be more complete by mentioning when to choose this tool over related siblings, but for the tool's complexity it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 3 parameters with descriptions (100% coverage), so the description adds no parameter-specific semantics. The baseline of 3 applies because the schema already documents each parameter (days, dataset, min_impressions) with defaults and thresholds. The description does not repeat or enrich these, but no extra burden is needed.
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 ('Find') and resource ('pages') with a clear qualifier: 'high impressions but CTR significantly below the expected benchmark for their ranking position.' It also names the practical output ('title and meta description optimisation candidates'), which distinguishes it from siblings like gsc_ctr_benchmark that likely just report benchmarks.
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 clearly frames the tool's purpose as identifying optimization candidates, implying when to use it (when looking for CTR/title/meta opportunities). It does not explicitly name alternatives or exclusions, but the user intent is evident. The 'IMPORTANT' instructions also clarify how the tool should be used for analysis, which adds guidance.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the tool trains a time-series model, requires historical data, and returns confidence intervals. It also adds important guidance on analyzing only returned data and avoiding speculation. It does not explicitly state whether it writes to BigQuery storage, but the 'trains a model' behavior is clearly disclosed.
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 front-loaded with the core purpose, but then includes a lengthy block about analysis and presentation instructions. While these instructions are valuable context for using the output, they are verbose. Every sentence earns its place, but the overall length could be trimmed without losing essential information.
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 complex forecasting tool with no output schema, the description explains what it returns (future clicks, confidence intervals) and gives prerequisites (6+ months historical data). It also provides guidance on how to report results. It does not describe exact output formatting, but that is acceptable given no output schema. Overall, it is complete enough for an AI agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters (dataset, horizon, confidence_level) with descriptions, so schema coverage is 100%. The description does not add any parameter-specific meaning beyond what the schema already provides. Baseline of 3 is appropriate.
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 function: 'Forecast organic traffic using BigQuery ML ARIMA_PLUS. Trains a time-series model on your historical click data and projects future clicks with confidence intervals.' This uses a specific verb ('forecast'), names the resource ('organic traffic', 'historical click data'), and distinguishes it from sibling tools like gsc_quick_wins or gsc_traffic_drops.
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 gives clear context for when to use the tool: 'Requires sufficient historical data (ideally 6+ months).' It also notes that this is 'only possible with BigQuery ML,' implying a prerequisite. However, it does not explicitly name alternative tools or specify when not to use it, so it falls short of a 5.
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?
With no annotations, the description carries the full burden and discloses substantial behavioral constraints: base analysis only on data returned, avoid speculation, admit insufficient information, and present as a rich visual artifact. This goes beyond the schema and gives clear execution boundaries, though data-source limitations or performance characteristics are not mentioned.
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 front-loaded with the purpose and then organized into clearly labeled 'IMPORTANT' and 'PRESENTATION' sections. While longer than the two-sentence ideal, each section carries distinct and necessary instructions (honesty rules and visualization requirements) that justify the length.
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?
There is no output schema, so the description compensates by specifying the key output metrics (clicks, impressions, CTR by intent category) and the expected artifact-based presentation. It is reasonably complete for a read-only analytics tool, though it does not define the exact regex patterns or edge-case handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'days' and 'dataset' already described in the input schema. The tool description adds no additional parameter-level detail, so the baseline score of 3 is appropriate.
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 identifies the specific operation ('Classify all your ranking queries by search intent') and the output metrics ('clicks, impressions, and CTR by intent category'), distinguishing this tool from sibling GSC analysis tools. The verb 'Classify' and resource 'ranking queries' are explicit.
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 provides clear context for when to use the tool (when intent categorization of queries is needed), but it does not explicitly name alternatives or state when not to use it. The 'IMPORTANT' and 'PRESENTATION' sections add further usage expectations around data honesty and output format.
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 are absent, so the description carries full burden. It discloses critical behavioral rules: base analysis only on returned data, report exact numbers, avoid speculation, and clearly state when data is insufficient. It also mandates artifact-based visualization with specific formatting. This goes beyond schema and gives the agent clear execution boundaries.
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 front-loaded with the purpose, then includes necessary IMPORTANT and PRESENTATION sections. While the presentation section is detailed, it earns its place by defining output format. Some redundancy (e.g., 'Make the output visually scannable') could be trimmed, but it's well-organized.
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 query tool with no output schema and no annotations, the description is thorough. It explains the tool's purpose, comparative methodology, diagnostic categories, analysis constraints, and presentation requirements. It doesn't specify the return data structure, but for a GSC query tool this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both days and dataset are described). The description adds no parameter-specific information beyond the schema, so the baseline of 3 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 opens with a specific verb+resource: 'Find pages that lost the most traffic recently.' It clearly distinguishes from sibling tools like gsc_content_decay by focusing on traffic drop diagnosis (ranking loss, CTR collapse, demand decline).
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 the tool is for analyzing recent traffic drops by comparing current vs prior period. It doesn't explicitly name alternatives or exclusionary cases, but the context is unambiguous. Sibling names like gsc_anomalies suggest overlap, but no direct comparison is made.
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?
With no annotations, the description carries the full burden. It discloses two important behavioral traits: only SELECT queries are allowed and a LIMIT clause is automatically added if missing. It also sets expectations for careful analysis. This provides meaningful behavioral context 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 concise and front-loaded, with the primary purpose in the first sentence. Each subsequent sentence adds value—constraints, workflow, and analysis guidelines. The IMPORTANT section is somewhat verbose but contains critical guidance. Overall, it's efficient without being excessive.
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?
Given that this is a complex SQL query tool with no output schema, the description is quite complete. It covers security constraints, automatic LIMIT addition, required schema exploration, and proper data interpretation. It doesn't address potential pitfalls like query errors or timeouts, but it provides sufficient context for an agent to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds some context around the sql parameter (SELECT-only) and the LIMIT behavior, which indirectly relates to max_rows. However, it doesn't provide significant enrichment beyond what the schema already describes for each parameter.
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 with a specific verb and resource: 'Run a SQL query against BigQuery and return results.' It adds the key constraint that only SELECT queries are allowed, which further clarifies scope and distinguishes it from general data manipulation tools.
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?
It provides a clear workflow: use list_datasets, list_tables, and describe_table first to understand the schema. It also instructs the agent to base analysis only on returned data and to state when data is insufficient. While it doesn't explicitly mention alternative tools like sample_rows or query_cost_estimate, the workflow guidance is strong.
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?
With no annotations, the description carries the full burden of behavioral disclosure. It adds strong guidance: 'Base your analysis ONLY on the data returned,' 'Do not speculate about causes,' and 'If the data does not contain enough information to answer a question, say so clearly.' It also mandates interactive visualization. This goes well beyond the basic purpose, though it does not cover every potential aspect (e.g., error conditions, costs).
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 longer than typical but is well-structured with a clear purpose, a single prerequisite, and detailed IMPORTANT/PRESENTATION sections. It is front-loaded with the core functionality, and each section serves a purpose given the complexity of the tool, though the presentation instructions are somewhat verbose.
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?
Despite having no output schema, the description comprehensively covers what the tool does, why it is needed, how to handle data limitations, and what output format to produce. It explicitly addresses the 'insufficient data' case and prescribes a rich interactive visualization, making it complete for an agent to invoke and use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for both parameters ('days' and 'dataset') with 100% coverage. The tool description adds no additional parameter-level detail; it only reiterates the BigQuery dataset requirement in prose. Since the schema handles parameter semantics, a baseline score of 3 is appropriate.
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 function: 'Analyse anonymous (hidden) query traffic that the GSC API cannot show' and specifies exactly what it reveals: 'what percentage of your clicks come from queries Google redacts, and which pages get the most hidden traffic.' This distinguishes it from sibling GSC analysis tools by focusing on hidden/anonymous traffic.
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 provides a clear prerequisite: 'Only possible with BigQuery bulk export,' which signals when this tool should be used. It does not explicitly name alternative tools or give exclusion criteria, but the unique scope is evident from the purpose statement, giving the agent enough context to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral transparency. It thoroughly discloses the join mechanism (normalised landing page URL), expected join rates (70-90%), potential mismatches due to URL normalisation, timezone differences, and sampling, and instructs the agent to report join rates and avoid speculation. This is exemplary 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 well-structured: the first sentence states purpose, followed by two IMPORTANT sections for data caveats and analysis rules. All sentences earn their place, though the two 'IMPORTANT' blocks make it slightly verbose. Overall, it is concise and front-loaded with the core purpose.
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?
Given the complexity of joining two data sources and the absence of an output schema, the description covers the critical caveats (join rate, timezone, sampling) and provides behavioral guidance. It does not specify the exact return format or granularity, but the purpose and constraints are sufficiently clear for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers 100% of the 5 parameters with descriptions. The tool description does not add additional parameter-level semantics, so the baseline score of 3 is appropriate. No gaps in parameter understanding are introduced.
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 what the tool does: it returns landing pages with both GSC search performance metrics (clicks, impressions, position) and GA4 engagement metrics (sessions, engagement rate, conversions) side by side. This distinguishes it from sibling tools that focus on query-level or revenue data, making the purpose highly specific and actionable.
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 provides clear context on when to use the tool: it requires GA4 BigQuery export and combines GSC and GA4 data for landing pages. It also gives important caveats like join rates and timezone differences, but does not explicitly name alternative tools or state when not to use this tool, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so thoroughly. It discloses the attribution method, URL normalisation join, variable join rates, timezone and sampling discrepancies, and instructs to report join rate and avoid speculation.
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 well-structured with a front-loaded purpose and clear IMPORTANT markers. However, the phrase 'The revenue per keyword metric SEOs have wanted for years' adds promotional rather than operational value, keeping it from a perfect conciseness score.
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?
The description thoroughly explains the complex join/attribution caveats and provides output-handling instructions. However, with no output schema, it does not explicitly enumerate the expected result fields (e.g., query, revenue, conversions), leaving some inference to the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 5 parameters have schema descriptions (100% coverage), so the baseline is 3. The tool description does not add extra parameter-level detail beyond the schema, such as date formats or dataset naming conventions, so it meets the baseline without enhancing 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?
The description clearly identifies the tool as query-level revenue/conversion analysis with a specific attribution methodology (proportional click-share). It distinguishes itself from sibling tools by focusing on 'revenue per keyword' rather than page-level metrics.
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?
It gives clear context (answering which queries drive revenue), a prerequisite (GA4 BigQuery export), and handling instructions (report join rate, base analysis only on returned data). However, it does not explicitly mention alternatives or when-not-to-use cases relative to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses important behavioral traits: URL normalization, join rate variability, timezone discrepancies (GSC Pacific vs GA4 property timezone), sampling, and instructions to report exact numbers and avoid speculation. It also tells the agent to acknowledge insufficient data rather than guess. This goes far beyond generic read-only hints and gives strong guidance on how results should be presented.
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 moderately long but each sentence earns its place, covering purpose, prerequisites, data caveats, and analyst guidelines. The use of 'IMPORTANT' emphasizes critical instructions. It could be slightly shortened by merging some caveats, but the structure is logical and not wasteful.
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?
Given the tool's complexity (cross-platform data join, analysis constraints) and lack of output schema, the description is quite complete: it explains data limitations, instructs on reporting exact numbers, and sets boundaries for speculation. However, it does not describe the expected output format or fields, which would help the agent know what to return beyond join rate and mismatch lists. Still, this is a minor gap for such a rich description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers 100% of the parameters with descriptions (days, max_rows, min_clicks, ga4_dataset, gsc_dataset), so the baseline is 3. The tool description does not add additional meaning to these parameters; it only indirectly references 'join rate' which is an output concept, not a parameter. Thus schema alone carries the 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?
The description clearly states the tool's purpose: 'Find pages where SERP snippet performance doesn't match on-site engagement.' It explains the two mismatch scenarios (high CTR/low engagement and low CTR/high engagement) and distinguishes this tool from sibling GSC/GA4 tools by focusing specifically on snippet-audience alignment, not just rankings or CTR.
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 gives clear context: it requires GA4 BigQuery export and notes that data is joined on normalized landing page URLs with typical join rates of 70-90%. It also warns about timezone and sampling differences. However, it does not explicitly mention when to use this tool over a sibling tool (e.g., ga4_gsc_page_performance) or when not to use it, so it lacks explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It goes beyond a simple description by specifying important usage rules: 'Base your analysis ONLY on the data returned', 'Report exact numbers', and 'Do not speculate about causes... unless the data explicitly supports it.' It also mandates a specific presentation format, which is a behavioral trait that greatly aids an agent in delivering consistent results.
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 longer than typical but is well-structured into purpose, output, analysis rules, and presentation rules. The first sentence immediately conveys the core function, and each subsequent section adds necessary guidance. The presentation section is detailed but earns its place for a tool that expects rich visual output. Slight verbosity prevents a perfect 5.
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?
There is no output schema, so the description must convey what the tool returns. It does so by listing 'pages to update, content to create, and pages to consolidate.' It also addresses how to handle insufficient data. However, it lacks specific details on result ordering, default behavior when parameters are omitted (although schema provides defaults), or any potential limitations, which keeps it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all three parameters (days, dataset, max_recommendations) with 100% coverage. The description adds no parameter-specific meaning, such as examples or expected values, beyond what the schema provides. Therefore, the baseline score of 3 is appropriate.
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 actionable content recommendations by cross-referencing quick wins, content gaps, and cannibalisation data.' It uses a specific verb and resource, and distinguishes itself from sibling tools like gsc_quick_wins and gsc_cannibalisation by explicitly combining these data sources. The output is also well-defined: 'prioritised actions: pages to update, content to create, and pages to consolidate.'
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 provides clear context for when to use the tool: when integrated content recommendations are needed, not just raw data. It mentions cross-referencing multiple data sources, which implies it should be selected over individual data source tools. However, it does not explicitly state 'use this instead of X' or list exclusions, so it falls short of a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states analysis rules: 'Base your analysis ONLY on the data returned', 'Report exact numbers', 'Do not speculate about causes', and 'If the data does not contain enough information to answer a question, say so clearly.' It also details the presentation format, including artifacts, summary cards, and color-coded indicators, which goes beyond the schema and adds significant behavioral context.
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 front-loaded with the core purpose, followed by important analysis rules and presentation requirements. While it is longer than the two-sentence ideal, every sentence adds necessary instructions for tool behavior and output format. The structure is logical and avoids redundancy, making it appropriately detailed for the tool's complexity.
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?
The description covers the tool's purpose, analysis constraints, and output presentation in detail, which is crucial given the lack of an output schema and annotations. However, it does not explicitly list the fields or metrics returned (e.g., keyword, impressions, position), leaving a minor gap in understanding the exact output structure. Overall, it is largely complete for a 4-parameter tool with clear scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema for individual parameters, but it does map the core concept of 'positions 4 to 15' to max_position and 'high impressions' to min_impressions. This alignment reinforces the tool's purpose without adding technical details that the schema already provides.
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 function: 'Find keywords from GSC bulk export data at positions 4 to 15 with high impressions' and identifies them as 'striking distance keywords that could be pushed to page one.' This uses a specific verb, resource, and scope, effectively distinguishing it from sibling tools like gsc_content_gaps or gsc_traffic_drops.
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 gives clear context for when to use this tool: when targeting keywords in positions 4-15 with high impressions to identify quick wins. However, it does not explicitly mention alternatives or exclusions, such as when to use gsc_ctr_opportunities or gsc_content_recommendations instead. The context is sufficient for an informed agent, but lacks explicit guidance on not using it.
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?
No annotations provided, so description carries full burden. It discloses the key behavior: dry-run, no execution, returns byte count. This is sufficient for understanding side effects, though it could mention permissions 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy, front-loaded with the core action. Efficiently communicates purpose and usage.
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?
For a simple tool with full schema coverage and no output schema, the description covers purpose, usage, and behavior comprehensively. The dry-run aspect makes context clear without needing more.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions, so description adds little beyond. The description of project_id as 'Override the default project ID' is already in schema; tool description adds no further 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?
Clearly states it performs a dry-run of a SQL query to estimate bytes scanned, distinguishing it from query execution. The phrase 'without actually executing it' makes the resource and behavior unambiguous.
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?
Explicitly advises using this before expensive queries as a cost check. It implies the alternative is actual execution, but does not name sibling tools or state when not to use it in explicit terms.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden of behavioral disclosure. It discloses data joining on normalized URLs, join rate variability (70-90%), potential mismatches due to timezone and sampling, and explicit instructions to report exact numbers and avoid speculation. This is detailed and actionable, going far beyond typical descriptions.
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 front-loaded with the core value proposition, followed by essential requirements and caveats. Every sentence earns its place, and the structure flows logically from purpose to prerequisites to important usage rules. It is appropriately sized for the tool's complexity.
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 complex tool with no output schema, the description gives strong operational context (how to handle data limitations and respond to queries). However, it does not describe the return format or how the 'diagnosis' is presented. This is a minor gap, as the agent could still use the tool effectively, but a clearer output description would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All five parameters are fully described in the schema, so baseline is 3. The description adds no additional parameter-level detail (e.g., how days interacts with timezone caveats). It does not compensate for gaps because there are none, but it also doesn't enrich the meaning of any parameter.
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 a specific dual purpose: find pages that rank well but don't convert and pages that convert but rank low. It also says 'Diagnoses each page,' adding a distinct analysis scope. This differentiates it from GSC-only tools and GA4+GSC performance tools by focusing on the rank-conversion gap.
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 provides strong context for when to use the tool, including the requirement for GA4 BigQuery export and the insight that it helps decide between fixing the page vs investing in SEO. However, it does not explicitly mention alternatives or when not to use it, though the 'fix the page, not the SEO' framing implies the type of decision it supports.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it delivers extensive behavioral guidance: it instructs the agent to base analysis only on returned data, report exact numbers, avoid speculating on causes without data support, and admit when data lacks information. It also mandates a specific dashboard-like presentation style. This goes well beyond a typical tool description.
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 structured with clear sections (core, IMPORTANT, PRESENTATION) and leads with the core purpose, but it is quite verbose, especially the presentation instructions which consume a large portion. Every sentence adds value, but the length may tax the agent's context; still, it's efficiently organized with key behavioral rules.
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 no output schema and no annotations, the description provides a remarkably complete picture: purpose, usage context, data prerequisites, analysis rules, and presentation requirements. The only omitted detail is the exact data return structure, but the presentation instructions imply a structured dashboard, making this sufficient for a 2-param tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema already describes both dataset and anomaly_threshold with 100% coverage, so the baseline is 3. The tool description adds no extra parameter-level detail beyond the schema, though it does mention the data history requirement, which is indirectly related to the dataset parameter. No further compensation needed.
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 opens with a specific verb+resource ('Detect traffic anomalies using BigQuery ML') and immediately distinguishes itself from traditional threshold-based alerts by explaining it accounts for seasonality and weekly patterns, setting it apart from sibling tools like gsc_alerts. This makes the tool's purpose unambiguous and clearly differentiated.
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 provides clear context for when to use it: it's for detecting genuinely unexpected traffic changes rather than simple threshold alerts, and it explicitly notes the need for at least 6 months of historical data. It lacks explicit named alternatives or a direct 'use this when...' formula, but the prerequisite and comparison give sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly instructs to base analysis only on returned data, report exact numbers, avoid speculation about causes, and acknowledge insufficient information. It also mandates a specific presentation style (rich, interactive visualization with artifacts, summary cards, colour-coded indicators, etc.), giving the agent clear expectations for behavior and output.
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 longer than average but well-structured: it starts with the core purpose, then adds behavioral constraints (IMPORTANT) and presentation requirements (PRESENTATION). The sentences are purposeful and not wasteful. However, the caps-lock section headers and detailed presentation instructions could be seen as slightly verbose, though they earn their place given the lack of an output schema.
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 that there is no output schema and no annotations, the description thoroughly compensates. It explains what the tool identifies, the criteria, the analytical constraints (data fidelity, no speculation), and the required presentation format. It is complete enough for an agent to invoke and produce the expected result without additional clues.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single 'dataset' parameter, which is documented as 'BigQuery dataset containing GSC data.' The description does not add additional meaning about this parameter (e.g., format, defaults, requiredness), so it provides no value beyond the schema. Baseline 3 is appropriate.
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 states a specific verb and resource: 'Find pages with consistent traffic decline over three consecutive months from GSC bulk export data.' It adds a clear criterion ('One bad month is noise; three is a problem') that distinguishes this from related tools like gsc_traffic_drops or gsc_anomalies, making the 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when there is a need to identify sustained declines over multiple months. It does not explicitly name alternative tools or state when not to use, but the three-consecutive-months criterion provides strong contextual guidance that differentiates from sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It goes well beyond a simple summary by instructing the agent to base analysis only on returned data, report exact numbers, avoid speculation, clearly state when data is insufficient, and always present results as rich visualizations. These detailed behavioral constraints significantly shape how the agent should use the tool.
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 front-loaded with a clear purpose sentence, followed by analytical guidance and presentation requirements. While the presentation section is lengthy, it provides valuable behavioral direction and does not feel wasteful. The structure is logical, but the extended presentation instructions prevent a perfect score.
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?
For a tool with 3 simple parameters and no output schema, the description is exceptionally complete. It defines the problem, explains the analytical caveats, instructs on evidence handling, and mandates a rich presentation format. No significant gaps remain for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: all three parameters (days, dataset, min_clicks) have meaningful descriptions. The tool description adds no additional parameter-level semantics, but the baseline of 3 is appropriate because the schema fully documents the 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 opens with a specific verb ('Find') and a precise resource ('queries where mobile and desktop rank different pages from your site'), clearly identifying the tool's function as detecting device-specific cannibalisation. This distinguishes it from the sibling gsc_cannibalisation by adding the device dimension, making the purpose unmistakable.
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 provides clear context for when to use this tool: it detects an issue 'invisible in the GSC UI and impossible to detect via the API's 3-dimension limit.' While this implies a specific use case, it does not explicitly name alternative tools or state when not to use it, so it lacks the explicit exclusion that would earn a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does so excellently: 'Base your analysis ONLY on the data returned', 'Do not speculate about causes', 'If the data does not contain enough information... say so clearly', plus explicit presentation requirements. This goes far beyond the schema and gives agents clear behavioral boundaries.
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 longer than typical, but each section adds value: purpose, analysis constraints, and presentation instructions are clearly separated with capitalized markers. It is front-loaded with the core purpose and structured effectively, though slightly verbose for a simple extraction tool.
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?
The description comprehensively covers what the tool does, how to interpret results, and how to present them, which is essential given the absence of an output schema and annotations. It gives agents enough context to perform the analysis correctly and deliver the expected dashboard-like output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so all parameters (days, dataset, min_query_count) are already described in the schema. The description adds no additional parameter-specific semantics, so the baseline score of 3 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 a specific action: 'Extract the most common meaningful terms across your entire query set, ranked by clicks.' It also differentiates itself with 'A lightweight alternative to keyword clustering', positioning it as a simpler term extraction tool compared to more complex clustering approaches.
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?
It provides usage context by positioning itself as a 'lightweight alternative to keyword clustering', implying when it should be used. However, it does not explicitly exclude or name sibling tools, such as gsc_topic_cluster, so there is no direct 'when not to use' guidance, keeping it just below the highest bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral burden. It explicitly instructs the agent to base analysis only on returned data, report exact numbers, avoid speculation without evidence, and disclose insufficient data. It also mandates a rich presentation style via artifacts. This is extensive behavioral disclosure beyond structured fields.
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 quite long but well-structured with clear sections (purpose, requirements, analysis rules, presentation). Every sentence adds necessary operational guidance, though the presentation paragraph is verbose. It's not wastefully padded, but could be tightened.
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 has one optional parameter, no output schema, and no annotations, the description is remarkably complete. It covers what the tool does, data prerequisites, how to interpret results, and how to present them. It also addresses edge cases like insufficient data, making it fully contextual for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'dataset' has a clear schema description ('BigQuery dataset containing GSC data'), giving 100% coverage. The tool description adds little beyond that, though it mentions the 12+ months requirement which indirectly informs dataset selection. Per rubric, high schema coverage sets a baseline of 3.
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 that the tool performs year-over-year seasonal traffic analysis, listing the specific metrics (clicks, impressions, CTR, position) and the YoY comparison. This distinguishes it from sibling tools by emphasizing the seasonal and long-term BigQuery data requirement.
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 gives clear context for when the tool is appropriate: it requires 12+ months of BigQuery data and explicitly notes impossibility with the 16-month GSC API. While it doesn't name alternative sibling tools for other cases, it provides a strong prerequisite and use-case signal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses the join methodology on normalized landing page URLs, typical join rate ranges, potential mismatches due to URL normalization, timezone differences (GSC Pacific vs GA4 property timezone), and sampling. It also instructs the agent to report join rates and avoid speculation, which is strong behavioral guidance.
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 front-loaded with purpose and metrics, then follows with necessary caveats. Though longer than average, each sentence adds operational value—especially the IMPORTANT warnings about join rates and analysis discipline. No fluff, but could be slightly trimmed.
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 no annotations and no output schema, the description is remarkably complete. It covers prerequisites, data caveats, and explicit instructions for handling uncertainty ('Report exact numbers... Do not speculate... say so clearly'), which is sufficient for an agent to invoke the tool correctly and interpret results safely.
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?
Schema covers 100% of parameters, so baseline is 3. The description adds meaningful context by clarifying that brand_terms defines the branded segment and non-branded is the implicit complement; it also lists the output metrics, helping the agent understand what the parameters produce.
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 begins with a specific verb and resource: 'Compare branded vs non-branded organic traffic with engagement and conversion overlay from GA4.' It clearly lists the metrics covered (clicks, CTR, engagement rate, conversions, revenue), distinguishing this tool from sibling GA4/GSC tools focused on page performance, query revenue, or content ROI.
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 makes the context clear: use this tool to compare branded vs non-branded traffic with GA4 engagement/conversion data, and it explicitly states the prerequisite 'Requires GA4 BigQuery export.' It does not name alternative sibling tools or explicitly state when not to use it, but the framing is sufficiently contextual.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses key behaviors: URL normalization joining, join rate variability, and reasons why numbers may not match dashboards (timezone, sampling). It also instructs the agent to report exact numbers and avoid speculation, adding transparency about interpretation.
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 moderately long but each sentence conveys necessary information, from the high-level question to explicit caveats. It is front-loaded with the purpose, though the repeated 'IMPORTANT' sections add length; still, no waste.
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 complexity and lack of an output schema, the description is remarkably complete: it specifies the output (conversion rate and revenue per click by position bucket), the data prerequisites, and interpretation guidance. It also addresses potential errors in matching dashboard numbers, covering what an agent needs to know.
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 schema already describes all 4 parameters with 100% coverage, but the description adds meaningful context: the default 90 days is explained as for statistical significance, and the GA4 BigQuery export requirement ties to the dataset parameters. This elevates value beyond schema 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 tool's purpose: to show the revenue and conversion value of each ranking position. It specifies the metric (conversion rate, revenue per click) and the position buckets, distinguishing it from other GA4/GSC tools that focus on pages, queries, or content.
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 indicates prerequisites (GA4 BigQuery export) and gives context on the default 90-day window and join rate considerations. However, it does not explicitly contrast with sibling tools or state when to use it over alternatives, though the purpose itself makes the use case clear.
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

Suganthans-BigQuery-MCP-Server MCP server

Copy to your README.md:

[![Suganthans-BigQuery-MCP-Server MCP server](https://glama.ai/mcp/servers/Suganthan-Mohanadasan/Suganthans-BigQuery-MCP-Server/badges/card.svg)](https://glama.ai/mcp/servers/Suganthan-Mohanadasan/Suganthans-BigQuery-MCP-Server)

Score Badge

Copy to your README.md:

[![Suganthans-BigQuery-MCP-Server MCP server](https://glama.ai/mcp/servers/Suganthan-Mohanadasan/Suganthans-BigQuery-MCP-Server/badges/score.svg)](https://glama.ai/mcp/servers/Suganthan-Mohanadasan/Suganthans-BigQuery-MCP-Server)

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/Suganthan-Mohanadasan/Suganthans-BigQuery-MCP-Server'

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