ga4_custom_dimensions

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

With no annotations, the description carries the full burden and does so well: it discloses two concrete prerequisites (Admin API enabled on the quota project, Viewer role on the GA4 property) and states the error behavior ('If it fails for access, the error explains how to fix it'). It does not describe the return shape or whether event and user dimensions are returned together, which keeps it short of a 5.

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 resource definition and the report-naming convention are front-loaded, followed by requirements and failure behavior — a sensible order with no filler. The only flaw is the mid-sentence language switch ('Lector (Viewer) en la propiedad de GA4'), which is a small readability blemish in an otherwise tight description.

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 single-optional-parameter, read-only listing tool with no output schema and no annotations, the description covers prerequisites, error handling, and how the results are consumed in reports. The remaining gap — what the response contains and whether it covers both event and user dimensions at once — is modest.

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 coverage is 100% and the single `property` parameter is fully documented in the schema, including the default behavior and a pointer to ga4_list_properties. The description adds no further semantics about the parameter, so the baseline 3 applies.

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 names the resource precisely ('Event and user parameters registered as custom dimensions') and even explains the report-time naming convention customEvent:/customUser:, which distinguishes it from ga4_create_custom_dimension and ga4_custom_metrics. However, it never states the operation — no verb such as 'list' or 'retrieve' — so an agent must infer that this is a read/list tool.

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?

It gives a genuine usage rule for the returned values ('Only these parameters can be used in reports'), but says nothing about when to call this tool versus ga4_custom_metrics or ga4_create_custom_dimension. The one routing hint present is indirect: 'ga4_check_access checks everything at once' points to a sibling for the access-diagnosis case.

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