Agent Central

Search terms

get_search_terms

Read-only

Returns customer search terms that triggered Sponsored Products and Sponsored Brands ads. Defaults to ad_product=auto, searching both SP and SB and returning ad_product on each row; set ad_product when you need one product only. Filter on the aggregated per-term totals with min_spend, min_orders, or zero_orders_only; these run server-side after grouping, so questions like which terms spent money without converting (zero_orders_only=true with min_spend) answer in one bounded call. Recent ~3 days may be incomplete. Does not include bidded target performance or Brand Analytics market volume/share; use get_keyword_performance or get_search_query_performance for those.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Max rows (1-1000, default 20).
`offset`	No	Pagination offset (0-100000, default 0). Use the returned pagination.next_offset to continue.
`keyword`	No	Filter by matched keyword text (LIKE match, use % for wildcards).
`sort_by`	No	Column to sort by	spend
`end_date`	No	Optional. YYYY-MM-DD. Defaults to today if omitted.
`min_spend`	No	Keep only search-term groups whose total spend in the window is at least this amount. Applied server-side after grouping, so wasted-spend questions stay bounded.
`ad_product`	No	Sponsored ad product to search. Defaults to auto, which searches both Sponsored Products and Sponsored Brands search-term reports and returns ad_product on each row.	auto
`match_type`	No	Filter by match type or auto-targeting expression type
`min_orders`	No	Keep only search-term groups with at least this many orders in the window. Applied server-side after grouping.
`profile_id`	No	Filter by profile ID
`sort_order`	No	Sort order	desc
`start_date`	No	Optional. YYYY-MM-DD. Defaults to 30 days ago if omitted.
`ad_group_id`	No	Filter by ad group ID.
`campaign_id`	No	Filter by campaign ID. With ad_product=auto, searches matching SP and SB search-term reports.
`search_term`	No	Filter by customer search term (LIKE match, use % for wildcards).
`ad_group_name`	No	Filter by ad group name (LIKE match, use % for wildcards).
`campaign_name`	No	Filter by campaign name (LIKE match, use % for wildcards)
`include_raw_rows`	No	False returns compact rows. Default true.
`zero_orders_only`	No	Keep only search-term groups with zero orders in the window (spend without conversion). Combine with min_spend to surface meaningful wasted spend in one bounded call.
`include_diagnostics`	No	True may add expanded freshness diagnostics. Basic empty-result data-window diagnostics are included by default when available.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`evidence`	No

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 7, 2026

TDQS

A4.3/5.0

Behavior3/5

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real behavior: filters run server-side after aggregation, recent ~3 days may be incomplete, and ad_product is returned per row in auto mode. The incompleteness caveat is a genuinely useful data-freshness disclosure, though no rate limits or auth prerequisites are mentioned.

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?

Five tightly packed sentences: resource definition first, then default behavior, filter semantics, a freshness caveat, and excluded scope. Each sentence carries unique information and the routing guidance is front-loaded.

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?

With 20 params, full schema coverage, an output schema, and complete annotations, the description supplies exactly the missing layer — grouping semantics, freshness caveats, and sibling routing. Nothing an agent needs to call this correctly is absent.

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 documents every parameter including limits and pagination. The description adds meaning for the aggregation filters (min_spend, min_orders, zero_orders_only run after grouping) and the ad_product default behavior, but leaves the LIKE-match semantics, sort options, and include_raw_rows/include_diagnostics behavior to the schema. Baseline 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?

States a specific verb and resource — returns customer search terms that triggered Sponsored Products and Sponsored Brands ads — and explicitly contrasts itself with get_keyword_performance and get_search_query_performance for target-level and market-volume data. An agent can distinguish it from siblings like get_brand_search_terms without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use guidance (default auto covers both SP and SB; set ad_product for one product only), a concrete usage pattern for waste detection (zero_orders_only=true with min_spend answers non-converting-spend questions in one bounded call), and names the alternative tools to use for adjacent needs. Nothing is left to inference.

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

All Agent Central tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.