ad_manager_google_upsert_segment

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

Annotations indicate idempotentHint=true, readOnlyHint=false, and destructiveHint=false, but the description adds no explanatory context. It does not state that an existing segment will be updated or a new one created, nor does it mention required authentication or side effects. With annotations present the bar is lower, but the description still fails to add behavior beyond the name.

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?

At two words, this is not conciseness but severe under-specification. It fronts no useful information and forces the agent to open the schema to learn anything. While concise in length, it sacrifices all value, and the calibration rubric explicitly treats under-specification as a failure, not conciseness.

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?

For a tool with 13 parameters, nested objects (ruleBasedUserList), enums, and no output schema, the description is grossly inadequate. It does not explain what a segment is, how to choose among segment types, what the fields mean in context (e.g., members for CUSTOM_SEGMENTS vs seedUserListIds for LOOKALIKE), or what the response represents. This is a complex tool requiring rich guidance that is entirely absent.

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 all 13 parameters have descriptions and the schema carries full semantic weight. The description provides no parameter context, but per the rubric, the baseline is 3 when schema coverage is high. It does not add or contradict anything.

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 states a verb and resource ('Upsert segment'), but it is essentially a rephrase of the tool name with no additional context about what a segment is or how it differs from sibling tools like ad_manager_google_upsert_audience. It does not clarify whether a segment refers to a remarketing, custom, or other Google Ads entity, leaving purpose ambiguous.

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?

There is no guidance on when to use this tool versus alternatives. No mention of prerequisites, when to create vs update, or how this relates to the many other ad_manager_google_upsert_* and ad_manager_google_delete_segment tools. The description provides zero decision support.

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