content_brief

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

With no annotations provided, the description must carry the burden. It reveals key behaviors: URL normalization, top-20 sorting, GA4 error handling, and question classification. However, it omits details like rate limits, auth requirements, or behavior on missing pages.

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 relatively concise and well-structured with clear steps. However, it includes implementation details (e.g., _normalize_url, try/except) that could be condensed without losing clarity.

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 tool's moderate complexity (combining GSC and GA4) and the existence of an output schema (which relieves the need to describe return values), the description provides a reasonable overview. It lacks specifics on parameter input formats and edge case handling.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions the four parameters (days, site, page_url, property_id) and hints at URL normalization, but does not explain formats, allowed values, or constraints beyond defaults.

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 states the tool's purpose: 'Gather SEO content intelligence for a single page: top queries, question queries, and GA4 engagement.' It specifies the output components and distinguishes from sibling tools that focus on raw search analytics or GA4 alone.

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 mentions usefulness for 'brief-writing, content refreshes, and intent analysis' and outlines steps, but does not explicitly state when to avoid this tool or compare it to alternatives like get_search_analytics or ga4_page_performance.

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