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

Annotations declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral detail: it specifies the response format (array of {externalId, name}), instructs to use externalId in config and show name to users, notes that locations must be the first criteria for LinkedIn, and mentions that years-of-experience is numeric and not retrieved via this tool. These details go well beyond the annotations and inform the agent's expectations.

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 information-dense but well-structured with clear headings (USE FOR, CRITERIA TYPES, OPERATION MODES, RESPONSE, CHANNEL) and bullet lists. It front-loads the purpose and usage, and every sentence contributes necessary guidance. Despite its length, it remains scannable and efficient.

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 complexity (5 parameters, multiple criteria types, three modes, no output schema), the description fully equips an agent: it covers how to list, search, and directly reference, explains the response shape, notes the LinkedIn-only constraint, and even flags edge cases like years-of-experience not being retrieved. Nothing essential is missing.

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?

While schema coverage is 100%, the description adds crucial interaction semantics: it explains how criteria_type and reference_type relate (reference_type auto-determined), when to provide search_terms (search-based criteria), the default and effect of exact_match, and the distinction between list and search modes. It also provides concrete examples of operation modes. This is meaningful added meaning beyond the schema.

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 retrieves available criteria and supported values for target group creation/updates, and it breaks down into list-based, search-based, and numeric categories. It names the exact resource and verb, and the detailed criteria types and operation modes make it unmistakable versus siblings like search_reddit_criteria or search_insights_criteria_fields.

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 includes a dedicated 'USE FOR' section listing concrete intents (e.g., 'what targeting criteria are available?', 'validate criteria before creating target group'), and it explains three operation modes with examples. It also states 'Only LINKEDIN supported,' which excludes other channels, and implicitly signals when not to use this tool. This is explicit and actionable.

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