search_keywords_by_source_export

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

Annotations already indicate safe read-only and idempotent behavior. The description adds value by disclosing the return format (JSON array of {searchKeyword, percentage} rows, up to 500) and the truncation behavior for large responses. It also notes that invalid inputs cause HTTP 400 errors, providing additional behavioral context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is succinct with two informative sentences plus a spec link. Every sentence serves a purpose: identifying the tool, contrasting with siblings, and specifying return behavior. The link to the API spec is additional but not essential. Overall, it is well-structured and front-loaded with key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema, the description adequately explains the return format (JSON array of rows, up to 500, truncation for large responses). It covers the key behavioral aspects but does not elaborate on error handling beyond invalid parameter HTTP 400 or the exact CSV format. For a read-only export tool, this provides sufficient context for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters. The description repeats the meaning of the `accept` parameter (json default, csv returns CSV string) and sourceKey enum values, but does not add substantial new information beyond what the schema provides. Therefore, it meets the baseline but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as an export variant of source-filtered search keywords, specifying the resource ('search keywords filtered by source') and the verb ('export'). It explicitly contrasts with sibling tools (search_keywords_by_app_export, search_keywords_partner_export), stating that this tool returns the FULL DATA directly as a JSON array rather than HAL download links, which differentiates it from similar exports.

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

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

The description provides clear context for when to use this tool ('UNLIKE the partner/by_app exports, this returns the FULL DATA directly') and mentions expected behavior (up to 500 rows, truncation for large responses). It does not explicitly list when not to use it or a direct alternative, but the contrast with other export tools implies the use case.

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