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

No annotations are present, so the description carries the full burden and largely meets it: soft-delete vs permanent purge, child resources affected, the absence of a programmatic undo, the not-found error, and the returned post-delete state are all disclosed. Gaps remain on required permissions/authorization and the actual expiration window (deferred to a support URL), and the appended boilerplate calling DELETE "irreversible" sits in mild tension with the trash/undo flow described in the first sentence.

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 core information is front-loaded well, but the entry bloats with a bare support URL, a generic "HTTP DELETE — removes the resource" gloss that repeats the first sentence, and a paragraph about request-body construction that is boilerplate across this tool family. Several sentences are reusable filler rather than tool-specific signal.

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?

An output schema exists, so return shape need not be spelled out, and the destructive consequence chain (trash → purge → children removed) is covered thoroughly. What is missing for a destructive, admin-level operation with no annotations is authorization prerequisites and a concrete expiration timeframe, both of which the agent would need before deciding to call it.

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%, so all five parameters including the required `name` pattern are already documented in the schema, which sets the baseline at 3. The description's note about typed parameters winning over `params` and `body_file` supplying a whole body largely restates the schema field descriptions rather than adding new semantics.

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?

States a specific verb and resource ("Marks target Account as soft-deleted") and clarifies the exact semantics with the "trashed" synonym. The closing line enumerates the sibling operations over the same resource (get, list, patch, provisionAccountTicket, runAccessReport, searchChangeHistoryEvents), so an agent can distinguish it from them without opening a schema.

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?

Gives concrete decision context: there is no API-level restore, restoration must go through the Trash Can UI, and unrecovered accounts are purged with all children after expiration. It also names the sibling set for the same resource, but it never states positively when to choose delete versus, say, patch or a read-only sibling — the agent must infer.

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

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

With no annotations, the description carries the disclosure burden and does establish this is a read (HTTP GET) returning JSON. However, it spends most of its behavioral content on request-body construction and `body_file`, which is irrelevant to a GET lookup, and says nothing about auth/scope requirements or error behavior.

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 purpose clause is front-loaded correctly, but the middle sentence about building request bodies from typed parameters or `body_file` is boilerplate that does not apply to a read lookup and actively risks confusing the agent. Roughly half the text is inapplicable machinery rather than information about this call.

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?

All five parameters are documented at full coverage and an output schema exists, so return shape need not be explained. The read-only nature is conveyed via the HTTP GET tag; the only real gap is that the inapplicable body/`body_file` prose leaves ambiguity about what is actually required.

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%, so the baseline is 3 and the `name` format/example are already in the schema. The only added semantics is the precedence rule that typed flags beat the `params` map, which is genuinely useful given `params` is a free-form map, but nothing is said about `query` 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?

States a specific verb and resource ("Lookup for a single Account") and tags it as [HTTP GET], so the agent knows exactly what it fetches. It also names the sibling set over the same resource, which helps disambiguate from list/delete/patch, though it does not spell out the distinctions itself.

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?

Alternatives are enumerated (delete, list, patch, runAccessReport, etc.), which implies when this one applies, but the description never states the condition that selects get over list or getDataSharingSettings. Usage is inferable from the name, not from guidance in the text.

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

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

With no annotations, the description does carry some burden, and 'HTTP GET' plus 'singletons' usefully signals a safe read of a single per-account object. It says nothing about permissions required, whether the settings are created on first access, or error behavior when no settings exist.

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 purpose is front-loaded, but roughly half the text is boilerplate about request bodies, `params` maps and `body_file` — machinery irrelevant to a bodyless GET — plus a bare list of seven sibling names with no routing value. That padding dilutes an otherwise two-sentence definition.

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?

An output schema exists, so return values needn't be explained, and the singleton + HTTP GET notes cover the essential shape of the call. What remains missing (auth scope, behavior when settings are absent) is minor for a simple read.

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 `name` pattern and format example are already fully documented in the schema. The description's only parameter-adjacent content is generic request-construction boilerplate (typed params vs `params` map, `body_file`) that adds no meaning for a GET.

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?

States a specific verb and resource ('Get data sharing settings on an account') and adds a useful qualifier: these settings are singletons, which distinguishes the call from the list-shaped siblings. It does not explicitly contrast itself against the sibling get/list on the same resource beyond listing their names, so it stops short of a 5.

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 sibling list (delete, get, list, patch, provisionAccountTicket, runAccessReport, searchChangeHistoryEvents) gives context but never says when to choose this tool over them or what preconditions apply. Usage is only inferable from the verb 'Get'.

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

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

With no annotations, the description carries the burden and does add real value: soft-deleted accounts are excluded by default, an empty list is returned when nothing matches, and accounts may lack GA properties. It does not cover auth requirements, pagination behavior, or result ordering.

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 account-specific content is front-loaded and useful, but the trailing boilerplate about JSON request bodies, typed flags winning over params, body_file, and a sibling enumeration is largely irrelevant for a GET/list call and dilutes the definition.

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?

An output schema exists, so return values need no explanation, and schema docs cover all seven parameters. Combined with the explicit default-exclusion and empty-result notes, an agent has enough to call it correctly; only pagination guidance is implied rather than stated.

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%, so the baseline is 3; the schema already documents pageSize, pageToken and showDeleted. The description only reinforces the showDeleted default behavior and says nothing extra about pagination or the generic query/params escape hatches.

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 opening sentence gives a specific verb and resource (returns all accounts accessible by the caller) and the note explicitly routes property-listing to the sibling ListAccountSummaries, so the tool is distinguishable from accountSummaries.list.

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 clearly states the retrieval use case and points to the alternative (ListAccountSummaries) for property access. It lacks an explicit 'don't use this when' statement, but the alternative naming gives strong context.

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

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

With no annotations, the description carries the burden and does well: it reveals PATCH semantics, the runtime safety-profile constraint (refused under --readonly), and the return shape (response resource as JSON). It doesn't discuss permissions or partial-vs-full replacement behavior, but the safety constraint is valuable non-obvious context.

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?

Purpose and the safety constraint are front-loaded in a compact form. The redundant 'updates the resource' restatement and the long sibling enumeration are slightly wasteful but don't obscure the message.

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?

The tool is complete enough: mutation semantics, safety constraint, body construction, and return form are all conveyed, and an output schema exists. Minor gap is the absence of guidance on updateMask behavior (partial update) versus the body, but nothing critical 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?

Schema coverage is 100%, so the schema already documents every parameter including the request_body fields and updateMask. The description restates the body's accepted fields and the params/body_file routing, adding only modest guidance beyond the schema. Baseline 3 is appropriate.

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?

States a specific verb+resource: 'Updates an account [HTTP PATCH]' and even clarifies the patch semantics. It lists the sibling operations over the same resource, though it doesn't spell out the semantic distinction (e.g., patch vs update). An agent can still clearly identify what this tool does.

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 discloses a key usage constraint — 'refused under --readonly safety profiles' — which tells the agent when the call will fail. However, it only names the sibling list without explaining when to choose patch over delete/get/list, so the guidance is implied rather than explicit.

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

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

With no annotations provided, the description carries the full burden and does reasonably well: it discloses HTTP POST, that it 'creates or triggers a change', that it is gated behind readonly safety profiles, and that it returns the API response resource as JSON. It omits permissions/authorization needs and what the ticket ultimately enables, which keeps it below 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 purpose is front-loaded and the content is dense but mostly on-point. However the final clause runs on without punctuation ('...whole via `body_file` Siblings over the same resource:') and the sibling enumeration plus body-mechanics repeat information already in the schema, diluting the signal.

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?

An output schema exists, so return values need not be explained, and the description still notes the response is JSON. For a 5-parameter, zero-annotation mutation tool it covers the safety profile and body construction well; the remaining gap is the absence of authorization/permission expectations and the lifecycle meaning of a 'ticket'.

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 baseline is 3; the schema already documents query, params, dry_run, body_file and the request_body fields account/redirectUri. The description restates that the body accepts account and redirectUri and mentions the params-vs-body_file routes, adding little beyond the structured data.

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?

It names a specific verb and resource ('Requests a ticket for creating an account') and is clearly not one of the read/list siblings. It enumerates sibling tools but does not say how this operation differs from them in practice (e.g., that the ticket is a prerequisite to account creation), so it stops short of a 5.

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 only usage signal is the incidental note that it is 'refused under --readonly safety profiles', which implies it belongs in a read-write context. The trailing sibling list is a navigation aid but provides no when-to-use/when-not routing or prerequisites (who may request a ticket, what to do with it afterwards).

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

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

Adds genuinely useful context beyond structure: retention limits, admin-only access, and 360 gating. However, the injected '[HTTP POST] — creates or triggers a change; refused under --readonly safety profiles' framing is misleading for what is a read/retrieval report and may cause an agent to avoid a safe read call, and the body is truncated mid-sentence ('Google Analyti').

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?

Purpose and eligibility are front-loaded, which is good, but the text is a concatenation of API docs, a misapplied POST/readonly warning, and a mechanical sibling list. The truncated final sentence is dead weight that costs 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?

An output schema exists and auth/retention constraints are covered, so an agent has most of what it needs. But the mismatch between the advertised property-level reporting and the accounts/ entity path, plus the ambiguous readonly-refusal note, leaves real doubt about correct invocation.

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 request body properties are fully typed, so the schema does the heavy lifting. The description enumerates body fields (dateRanges, dimensions, metrics, filters) which is marginally helpful but largely duplicative, and it never clarifies the account-vs-property semantics of the required `entity` path.

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?

Opens with a specific verb + resource: 'Returns a customized report of data access records', clarifying this is a data-access audit report, not a metrics report. It does not cleanly distinguish itself from the sibling analyticsadmin.properties.runAccessReport, and it confusingly says reports 'can be requested for a property' while the entity parameter is an accounts/ path.

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?

Gives real eligibility rules: Administrators-only, 2-year retention window, and the 360-only restriction on non-quota dimensions. These preconditions meaningfully gate calling it, though there is no explicit statement of when to prefer this over analyticsdata runReport or the property-level sibling.

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

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

With no annotations, the description carries the full behavioral burden. It usefully notes that the tool returns only the subset of changes supported by the API and that the UI may return additional changes, and it flags the --readonly safety-profile refusal. However, the parenthetical '[HTTP POST] — creates or triggers a change' is misleading for a search operation and could confuse an agent about mutability.

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 purpose is front-loaded and useful, but the paragraph is long, run-on, and mixes behavioral notes, request-body structure, and sibling listing. Several clauses could be tightened or moved, and the misleading HTTP POST note distracts from the core read-only search purpose.

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?

Output schema exists, so return values need not be explained. The description still omits practical details such as pagination behavior and rate-limit considerations, and the usage-versus-alternatives story is incomplete. It covers the basic shape of the call but leaves gaps for an agent deciding how to use it.

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 and nested request-body fields. The description repeats the field names (action, actorEmail, earliestChangeTime, etc.) and explains that they can be passed via `params` or `body_file`, but adds little 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 states a specific verb and resource: 'Searches through all changes to an account or its children given the specified set of filters.' It distinguishes from siblings by listing the other account-level tools, though it does not explain how each sibling differs. An agent can tell it is a change-history search rather than a general list or get.

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 explicit guidance on when to use this tool versus alternatives. The sibling list names delete, get, list, patch, etc., but does not say which conditions favor searchChangeHistoryEvents over those. The agent must infer usage from the purpose sentence alone.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose '[HTTP GET]' (signaling a safe read) and explains request-body construction mechanics, but it omits auth requirements, pagination behavior, and what 'accessible by the caller' entails. The body_file guidance is generic boilerplate that is arguably irrelevant for a GET list endpoint.

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 purpose is front-loaded in a single clear sentence. The second sentence is long and generic boilerplate about JSON and request bodies that does not earn its place for this specific GET list endpoint.

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?

An output schema exists so return values need no explanation, and schema coverage is full. However, with no annotations and no usage guidance, the description leaves gaps around pagination expectations, authentication, and how this differs from accounts.list.

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 six parameters thoroughly. The description merely repeats the typed-parameters-win-over-params-map rule and the body_file override, adding no new 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?

States a specific verb ('Returns'), resource ('summaries of all accounts'), and scope ('accessible by the caller'). It does not explicitly differentiate from the closely named sibling analyticsadmin.accounts.list, but an agent can tell what resource is returned.

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 only describes what the tool returns; it gives no indication of when to use this versus alternatives like accounts.list or properties.list, nor any conditions or exclusions.

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

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

With no annotations present the description carries the full burden, and it does well: it discloses HTTP POST, that it creates/triggers a change, that it is refused under --readonly safety profiles, and that it returns the response resource as JSON. It stops short of noting auth requirements or irreversibility, keeping it at 4.

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?

Purpose and prerequisite are front-loaded, and most sentences carry weight. The trailing sibling enumeration is long and of marginal value, slightly diluting efficiency.

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?

With an output schema present and full schema coverage, the description needn't explain return values and correctly omits detail there. It supplies the key prerequisite and mutation behavior, leaving only minor gaps like auth context.

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%, so the schema already documents property, params, body_file, and the request_body shape. The description largely restates the params/body_file passing mechanism already captured in the schema and adds little beyond the baseline.

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?

States a specific verb (Acknowledges) and resource (the terms of user data collection) scoped to the property, and explicitly names the sibling operations over the same resource so it is distinguishable without opening a schema. The prerequisite relationship to MeasurementProtocolSecret is also surfaced.

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?

Provides strong context for when this is needed (before MeasurementProtocolSecret resources may be created) and names the alternative path (the GA UI or this API). It does not explicitly state when-not to call, so it falls just short of the top tier.

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

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

With no annotations, the description carries the burden well: it declares the HTTP method (POST), that it creates or triggers a change, that it is refused under --readonly profiles, and that it returns the API response resource as JSON. It omits permissions/scopes required and duplicate-handling or error behavior, which keeps it below 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?

Front-loaded with the deprecation warning and the core verb, which is the right order. It is dense but nearly every clause carries information, though the field list recital at the end is partly redundant with the schema and could be trimmed.

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 an output schema exists, the description needn't explain return values, and it still notes they come back as JSON. Parameters are fully covered by the schema, and the deprecation, mutation semantics, and readonly refusal are all disclosed; only auth requirements are unaddressed.

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%, so all six parameters including the nested request body are already documented structurally. The description restates the body fields and the params/body_file merge rule, which is marginal added value; the baseline 3 applies when the schema does the heavy lifting.

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?

States a specific verb and resource ('Creates a conversion event') and immediately flags the tool as deprecated in favor of CreateKeyEvent, which lets an agent distinguish it from the keyEvents.create sibling without opening either schema. It further enumerates the sibling operations (delete, get, list, patch) over the same resource.

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 very first token is a directive: 'Deprecated: Use `CreateKeyEvent` instead.' That is an explicit when-not-to-use statement paired with a named alternative, plus a note that readonly safety profiles refuse the call. Nothing about selection is left to inference.

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

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

With no annotations, the description carries the full burden and does disclose irreversibility ('irreversible unless a trash/undo flow exists'), refusal under --readonly profiles, and the post-delete return shape. That is meaningful behavioral context most delete tools omit.

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?

Front-loaded with the deprecation notice and the core action, with sibling routing at the end. Dense but nearly every clause earns its place, aside from the somewhat generic request-body mechanics sentence.

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?

Covers purpose, deprecation, safety profile behavior, and return format, and an output schema exists so return values needn't be detailed further. Adequate for an agent to call correctly without opening the schema.

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 parameter meaning is already documented. The description adds only marginal value by noting that typed parameters win over the params map and that body_file can supply the body; it does not explain the required `name` format beyond what the schema provides.

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?

States a specific verb and resource ('Deletes a conversion event in a property') and immediately flags deprecation. It also distinguishes this from its same-resource siblings (create, get, list, patch), so an agent can place it precisely.

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?

Explicitly routes the agent away with 'Deprecated: Use DeleteKeyEvent instead' and names the sibling CRUD operations on the same resource. Clear selection context, though it doesn't spell out the remaining legitimate conditions for using delete at all.

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

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

With no annotations, the description carries the full burden; it does disclose that this is an HTTP GET returning the resource as JSON, which signals a read-only operation, plus the deprecation status. It says nothing about authorization/scopes, error behavior for a missing or malformed resource name, or idempotency, and the body-building/body_file prose is irrelevant for a GET and adds noise rather than insight.

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?

Deprecation and purpose are correctly front-loaded, but the second sentence lards in request-body construction and body_file precedence that are meaningless for a GET retrieval, so not every sentence earns its place.

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?

An output schema exists, so return-value detail is not required, and all five parameters are fully documented in the schema, leaving deprecation and read-only nature as the main things the description must convey — which it does. Missing auth/permission context keeps it short of a 5.

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%, including the resource-name pattern and format example, so the schema already does the heavy lifting and baseline 3 applies. The description's mention that typed parameters win over the params map and that body_file can supply the body largely restates what the schema fields already say.

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?

States a specific verb and resource ("Retrieve a single conversion event") and explicitly enumerates the sibling operations over the same resource (create, delete, list, patch), so an agent can distinguish it from those siblings without inspecting schemas. The deprecation pointer to GetKeyEvent is front-loaded.

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 clear routing instruction — deprecated, use GetKeyEvent instead — and lists the sibling operations to contrast against, implying use list to enumerate and patch/delete to mutate. It does not spell out explicit when-not conditions beyond the deprecation notice.

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

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

With no annotations, the description carries the burden: it discloses deprecation, that this is an HTTP GET (read-only), and that an empty list is returned when nothing matches. However, the generic 'request bodies are built from the typed parameters... or read whole from `body_file`' boilerplate describes body construction that a GET never performs, which is noise bordering on misleading for this operation.

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?

Deprecation and purpose are correctly front-loaded in the first two sentences, but the trailing HTTP/body_file/params boilerplate is irrelevant to a read-only list call and dilutes the useful content. Trimming that sentence would improve the definition materially.

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?

An output schema exists, so return-value detail is not required, and the required `parent` plus pagination parameters are fully covered by the schema. Combined with the deprecation notice and empty-list behavior, an agent has nearly everything needed; the only real gap is the unresolvable `ListKeyEvents` alternative name.

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 seven parameters (parent, pageSize, pageToken, query, params, dry_run, body_file) are already documented in the schema; baseline 3 applies. The description adds no parameter-specific semantics — its only parameter-adjacent content (typed flags win over `params`) simply restates the schema's own `params` description.

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?

Specific verb+resource+scope: lists conversion events within a specified parent property, and explicitly names the four sibling operations on the same resource (create, delete, get, patch) so the agent can pick list without opening schemas. The deprecation notice front-loads the most decision-relevant fact.

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?

Says to use `ListKeyEvents` instead, which is a genuine when-to-use/alternative signal, but `ListKeyEvents` is not a resolvable tool name — the actual sibling is analyticsadmin.properties.keyEvents.list, so the agent must infer the mapping. No conditions or exclusions beyond the deprecation notice.

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

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: it discloses that the operation is a mutation blocked by --readonly profiles, that the response is the API resource as JSON, and how the body can be supplied (params vs body_file). This is exactly the safety and side-effect context the annotations would otherwise provide.

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?

Dense but front-loaded: the deprecation warning and replacement come first, then mechanics. It packs a lot into few sentences, though the trailing sibling enumeration is the least essential clause and could be trimmed without losing guidance.

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 mutating, deprecated tool with an output schema present, the description covers everything an agent needs: deprecation, replacement, read-only refusal, body construction options, and required updateMask semantics are handled by the schema. Nothing material 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?

Schema coverage is already 100%, so baseline would be 3, but the description adds real value: it enumerates the accepted body fields (countingMethod, createTime, custom, defaultConversionValue, deletable, eventName, name) and explains the two body-passing channels, params and body_file. That clarifies the interplay between the body_file, params, and request_body parameters beyond the schema text.

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?

States a specific verb and resource (updates a conversion event), leads with a deprecation notice naming the replacement UpdateKeyEvent, and distinguishes itself from the create/delete/get/list siblings over the same resource. An agent can identify what it does and which tool supersedes it without opening the schema.

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?

Explicitly routes the agent away from this tool ("Deprecated: Use UpdateKeyEvent instead") while naming the sibling set for the same resource. It adds the concrete condition that the call is refused under --readonly safety profiles, so an agent knows both the preferred alternative and a hard usage constraint.

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

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

With no annotations, the description carries the burden and discloses meaningful behavior: it is an HTTP POST that creates or triggers a change, is refused under readonly profiles, returns the API response as JSON, and accepts the request body via `params` or `body_file`. It does not describe required auth scopes or idempotency, but it provides substantially more behavioral context than a bare mutation description.

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 purpose is front-loaded and the description avoids filler. It is dense and packs multiple clauses plus a sibling list into one paragraph, which is informative but slightly harder to scan than a shorter multi-sentence structure.

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?

The tool is complex, but the description covers the mutation nature, return behavior, request body type, and input pathways. Since an output schema exists, it need not explain return values in detail; remaining gaps are mainly around permissions and precise when-to-use routing.

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 already 100%, so the baseline is 3. The description adds value by identifying the request body as a GoogleAnalyticsAdminV1betaProperty object, naming several accepted fields like account, createTime, currencyCode, displayName, and industryCategory, and clarifying that it can be passed via `params` or `body_file`.

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 specific verb and resource: 'Creates a Google Analytics property with the specified location and attributes' and adds HTTP POST. It also names sibling operations over the same resource, so an agent can distinguish this creation tool from get, list, patch, delete, and related operations.

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?

Usage is clearly implied for creating a new property and the description explicitly notes it is 'refused under --readonly safety profiles,' which is useful invocation context. It lists sibling tools but does not explicitly say when to prefer create versus patch or update, so it lacks full alternative-selection guidance.

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

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

With no annotations, the description carries the disclosure burden and does it well: HTTP POST, 'creates or triggers a change', explicit refusal under readonly profiles, and return of the API response resource. It stops short of saying whether archiving is reversible or what permissions/scopes are required, which keeps it from 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 core action and the readonly caveat come first, followed by return format and body-passing mechanics; every clause is load-bearing and there is no filler despite the dense em-dash construction.

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 mutating call with no annotations, the description covers action, mutation semantics, safety-profile behavior, return type, and body-passing mechanics, and an output schema exists so return values need no elaboration. Missing only prerequisites such as required permissions or reversibility of the archive.

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 baseline is 3. The description restates that the body is a GoogleAnalyticsAdminV1betaArchiveCustomDimensionRequest passed via `params` or `body_file`, but that duplicates what the schema already documents for those properties rather than adding new meaning.

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?

States a specific verb and resource ('Archives a CustomDimension on a property') and names the sibling operations over the same resource (create, get, list, patch), so an agent can distinguish it without opening another schema.

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 real usage constraint — refused under --readonly safety profiles — which tells the agent when the call will not work, and it lists sibling operations. But it does not say when to archive versus patch or delete a custom dimension, so the choice guidance is only implied by the sibling enumeration.

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

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

With no annotations, the description carries the full burden and does well: it flags HTTP POST mutation semantics, warns the call is refused under --readonly safety profiles, and cites a ToS restriction on individual-user data. It omits permission/OAuth scope requirements and idempotency behavior, keeping it from 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?

Front-loads the core action and warning, and every clause is relevant (ToS, mutation safety, body mechanism, siblings). It is somewhat dense with bracketed asides and em-dashes, which slightly hurts readability but wastes little.

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?

An output schema exists, yet the description still clarifies that the response resource is returned as JSON, and it covers the required parent, body fields, safety profile, and sibling alternatives. Only auth-scope and idempotency details are missing for a mutation tool with no annotations.

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%, so the schema already documents every parameter including parent, params, and body_file. The description restates the body fields (description, disallowAdsPersonalization, displayName, name, parameterName, scope) but adds no syntax or format meaning beyond the schema — 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?

Opens with a specific verb+resource ("Creates a CustomDimension") and explicitly enumerates the sibling set over the same resource (archive, get, list, patch), so an agent can immediately distinguish create from patch/archive without opening the schema.

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 named siblings imply when this tool is preferred over patch/archive, and it tells the agent to supply the body via `params` or `body_file`. It stops short of an explicit 'use this when you need a new dimension vs. modifying an existing one' statement, leaving some inference.

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

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

No annotations are provided, so the description carries the burden. It discloses that this is an HTTP GET returning JSON, which establishes the read-only safety profile, but the request-body/body_file discussion is largely irrelevant to a GET and there is no mention of auth scopes, permissions, or error behavior.

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 purpose is front-loaded and the sibling list is efficient. However, the clause about building request bodies from typed parameters or body_file is boilerplate noise for a GET lookup that accepts no meaningful body, spending words that don't earn their place.

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?

An output schema exists and the input schema is fully described, so return values and parameters needn't be re-explained. The definition is sufficient to call it correctly; the only gap is absent auth/permission context, which is minor for a simple get.

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%, so the schema already documents all five parameters, anchoring the baseline at 3. The description adds precedence semantics ('typed flags win over the params map', body_file override) that isn't in the schema, but it is generic template text rather than tool-specific guidance.

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?

States a specific verb and resource ('Lookup for a single CustomDimension') and explicitly names the sibling operations over the same resource (archive, create, list, patch), so an agent can distinguish get from list without opening a schema.

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?

Naming the sibling set (archive/create/list/patch) routes the agent away from those when fetching one item, giving clear context. It does not explicitly state the when-to-use condition (e.g. 'use list to enumerate, get when you have a name'), so it falls short of full 5-level guidance.

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

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

No annotations are provided, so the description carries the full burden. It usefully signals '[HTTP GET]' and that a JSON resource is returned, but says nothing about required permissions, pagination behavior, or result ordering — significant gaps for a 7-parameter listing endpoint.

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 first sentence is front-loaded and precise, but the second sentence is generic boilerplate about request bodies being built from typed parameters or `body_file` — largely irrelevant for a GET listing — which dilutes the definition.

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?

An output schema exists so return values needn't be explained, and all 7 parameters are documented in the schema. Sibling routing is present; only permission and pagination nuance is missing, which is minor given the structured coverage.

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 parent, pageSize and pageToken are already documented. The description adds a little context about typed flags winning over the `params` map and `body_file`, which is a marginal value-add over the schema baseline.

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?

States a specific verb and resource with its scope: 'Lists CustomDimensions on a property'. It also names the sibling operations over the same resource (archive, create, get, patch), so an agent can distinguish list from get without opening a schema.

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 sibling list implies routing (use list to enumerate, get for a single record, patch to modify), but the description never states a when-to-use condition or any prerequisite. Usage is only implied rather than explicit.

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

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

With no annotations, the description carries real behavioral weight: it discloses the HTTP PATCH mutation semantics, the readonly-profile refusal, and that the response resource is returned as JSON. It doesn't cover permission requirements or reversibility, but it is well above the annotation-free baseline.

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?

Front-loads the core action and the readonly constraint, then covers return value, body, and siblings. Some redundancy with the schema (body field list, params vs body_file), but every clause still serves a purpose and nothing is bloated.

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 mutation tool with a 7-param nested schema and an existing output schema, the description supplies the key missing pieces: mutation nature, safety refusal, and body-passing mechanism. Complete enough to invoke correctly, with the noted updateMask omission being minor given the schema covers it.

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 baseline is 3. The description restates the body fields (description, disallowAdsPersonalization, displayName, name, parameterName, scope) and the params/body_file mechanism, but this largely duplicates what the schema already documents, and it omits the required updateMask nuance.

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?

States a specific verb and resource ('Updates a CustomDimension on a property') and explicitly names the sibling operations over the same resource (archive, create, get, list), so an agent can distinguish patch from create/archive without opening any schema.

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?

Provides clear context for when the tool applies and a useful when-not signal ('refused under --readonly safety profiles'), plus names the sibling alternatives. It stops short of routing the agent with explicit conditions for choosing patch vs create vs archive, so it is a strong 4 rather than a 5.

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

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

With no annotations, the description carries the full burden and does well: it declares the HTTP POST verb, that this mutates state, the read-only-profile refusal, and that the API response resource is returned as JSON. It omits whether archiving is reversible or what happens to the metric's historical data, which is the main behavioral gap for a mutation.

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 mutation and its safety-profile constraint are front-loaded ahead of the mechanical body details, which is the right ordering. It runs long as a single sentence chain and repeats the archive request body type in both `params`/`body_file` and `request_body` framing, costing a little density.

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?

An output schema exists, so return values need no explanation, and the description covers verb, refusal condition, body transport, and sibling set. For a 6-parameter mutation tool with nested body objects, the missing piece is the effect of archiving (reversibility, impact on reporting), which an agent would want before firing.

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 every parameter including the `name` pattern and body type is already documented in structured form. The description restates the body-passing convention (`params` vs `body_file`) but adds no new semantics beyond the schema, so 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?

States a specific verb and resource ("Archives a CustomMetric on a property") and immediately enumerates the sibling operations over the same resource (create, get, list, patch), so an agent can place it in the CRUD family without opening a schema. The required `name` pattern pins the exact resource addressed.

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?

"Refused under --readonly safety profiles" is a genuine precondition that tells an agent when the call will fail, and listing the sibling operations hints at the family. However, it never says when to choose archive over patch (e.g., retiring a metric) or whether archiving is reversible, so the selection criteria remain implied.

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

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

With no annotations present, the description carries the full burden and does real work: it discloses that this is a mutating POST, that it is blocked under --readonly profiles, that it returns the API response resource as JSON, and that the body may be supplied either merged via `params` or wholesale via `body_file`. It stops short of stating required auth scope or duplicate-name behavior.

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 purpose is front-loaded in the first clause and there is no filler prose, but the long em-dash chain is dense and the seven-field enumeration duplicates what the schema already lists, which is the one stretch that does not earn its place.

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?

An output schema exists, so the return-value gloss is optional and adequately covered. For a 6-parameter mutation tool with no annotations, however, the description omits the practical prerequisites an agent needs before calling it — permissions/scope, whether a duplicate displayName is rejected, and whether the created metric is immediately usable.

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 baseline is 3. The description re-enumerates the body fields (description, displayName, measurementUnit, name, parameterName, restrictedMetricType, scope) and the params/body_file routing, both of which are already documented in the schema, so it adds little meaning beyond structured data.

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?

States a specific verb and resource (creates a CustomMetric under a GA4 property) and explicitly names the sibling operations over the same resource (archive, get, list, patch), so an agent can place it in the CRUD set without opening another schema. The '[HTTP POST]' marker reinforces the write nature.

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 lists the sibling operations over the same resource but never says when to choose create over patch, or what preconditions apply (e.g. metric must not already exist). The only operative guidance is the negative one: it 'is refused under --readonly safety profiles.' Usage is implied rather than routed.

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

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

No annotations are provided, so the description carries the full disclosure burden; it does declare the operation is an HTTP GET returning JSON, which tells the agent this is a non-mutating read. However, it says nothing about auth/permission requirements, error behavior for a missing or malformed name, or rate limits, and spends a sentence on body-construction mechanics that are irrelevant to a GET.

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?

Two short sentences with the purpose and resource scope front-loaded, followed by the sibling enumeration. The body/params precedence clause is low-value for a GET call and could be dropped, but the text is compact overall.

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?

An output schema exists, so return values need not be explained, and the required path parameter is fully specified in the schema. Combined with the HTTP GET disclosure, an agent has enough to invoke it correctly; only permission/error context is missing, which is a minor gap for a simple read tool.

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 every parameter including `name` with its pattern and example is already documented in the schema. The description's only extra claim — typed parameters win over the `params` map and `body_file` can supply a body — restates the schema's own wording and is boilerplate for this endpoint, so 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?

States a specific verb and resource ("Lookup for a single CustomMetric") and explicitly separates itself from the sibling operations over the same resource (archive, create, list, patch). The only weakness is the slightly loose verb "Lookup" and the prefixed HTTP GET note, but an agent can still tell it retrieves exactly one CustomMetric.

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?

Naming the sibling set implies when to use this tool (single-resource retrieval versus list/create/patch), but the description never states a condition such as "use list to enumerate" or any prerequisite like required permissions or a fully-qualified resource name. Usage has to be inferred rather than read.

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

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

With no annotations, the description carries the full burden. It discloses the safe read profile via '[HTTP GET]' and that the result is JSON, which is genuinely useful. However, the majority of the second sentence describes request-body construction and body_file mechanics that are irrelevant to a GET list call, and it says nothing about pagination behavior, permissions, or rate limits.

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 purpose is front-loaded and the sibling sentence earns its place, but the intervening sentence about typed parameters overriding the params map and reading whole bodies from body_file is boilerplate noise for a list endpoint and dilutes an otherwise short definition.

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?

An output schema exists and all seven parameters are fully documented in the schema, so the description need not explain return values or pagination mechanics. Combined with the explicit sibling list and GET indication, this is complete enough to call correctly.

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 baseline is 3; the schema already documents parent, pageSize, pageToken, dry_run, params, query and body_file. The description adds no parameter-level meaning and in fact muddies things by discussing body_file/body-building for a query-only operation.

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 specific verb and resource ('Lists CustomMetrics on a property') and names the sibling verbs over the same resource (archive, create, get, patch), so an agent can place it as the enumeration variant. It falls short of a 5 because the siblings are merely enumerated without routing guidance.

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?

Listing the sibling operations implies this is the tool for enumerating existing custom metrics rather than mutating or fetching a single one, but it never states when to prefer list over get, nor any exclusions or prerequisites. Usage is inferable rather than spelled out.

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

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

With no annotations, the description carries the full burden and does add real value: it discloses that the call is refused under --readonly safety profiles, describes the return (response resource as JSON), and explains the params vs body_file body-construction paths. It omits permission/OAuth scope requirements, idempotency, and partial-update semantics (which fields change / are left untouched), which are significant for a mutation tool with zero annotation coverage.

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?

Front-loads the action and method, which is good, but then crams body field enumeration, the params/body_file mechanism, and the sibling list into one dense run-on. The field list duplicates schema content and could be trimmed.

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?

Output schema exists and the input schema is fully described, so the core is covered; the safety-profile refusal is a useful addition. However, for a mutation tool with no annotations and a required updateMask, the description should also flag permission requirements and the partial-update implication of updateMask.

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 name, updateMask, query, params, dry_run, and body_file. The description still adds value by stating the body object type and the two ways to supply it (params merge vs whole body_file), though it redundantly re-enumerates body fields already in 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?

States a specific verb (updates) and resource (CustomMetric on a property), and the HTTP method [HTTP PATCH]. It explicitly names the sibling operations over the same resource (archive, create, get, list), so an agent can place it precisely in the CRUD family without opening a schema.

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 names the sibling tools but never states when to choose patch over update/create/archive, nor what prerequisites (e.g., updateMask, permissions) select it. Usage is implied by the PATCH verb and sibling list rather than spelled out.

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

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

With no annotations, the description carries the behavioral burden and does well: it identifies the operation as HTTP POST, states that it creates or triggers a change, discloses refusal under --readonly safety profiles, and says it returns the API response resource as JSON. It still omits required permissions or rate-limit behavior, keeping it below 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 key purpose and safety-profile constraint are front-loaded, and every part of the description is relevant. The single long sentence is dense and somewhat run-on, but it avoids filler and keeps useful details.

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 a mutation with a nested request body, full schema description coverage, and an output schema, the description is largely complete: it covers body shape, params/body_file usage, sibling operations, and readonly refusal. It does not mention authorization or required roles, which leaves a small completeness gap.

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 baseline is 3. The description repeats the GoogleAnalyticsAdminV1betaDataStream body type and the params/body_file split, both of which are already documented in the schema, so it adds little parameter meaning beyond structured fields.

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 specific verb and resource — 'Creates a DataStream' — and immediately names the sibling operations delete, get, list, and patch over the same resource. An agent can distinguish this create tool from the other data stream tools without inspecting schemas.

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 clear when-not condition: the operation is refused under --readonly safety profiles. It also lists sibling operations over the same resource as alternatives, though it does not explicitly route the agent between create and patch for existing resources.

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

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

No annotations are provided, and the description carries the full burden well: it discloses irreversibility (with the honest caveat about a possible trash/undo flow), the refusal behavior under read-only safety profiles, and the post-delete return payload. That is substantially more than the name implies.

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?

Front-loaded with the destructive action and its consequences, which is the right ordering for an irreversible tool. The trailing sentence about typed flags vs params map vs body_file is generic boilerplate repeated across the tool family and dilutes the core message slightly.

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?

Output schema exists, so the return shape needs no elaboration, yet the description still notes the post-delete JSON state. Combined with the irreversibility warning and safety-profile refusal, an agent has everything needed to decide and call correctly.

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 every parameter already has its own description, including the typed-parameters-win precedence rule and body_file semantics. The description largely restates that resolution order rather than adding format or constraint detail beyond the schema, so 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?

States a specific verb and resource ('Deletes a DataStream on a property') plus the HTTP method, and explicitly names the sibling set over the same resource (create, get, list, patch). An agent can distinguish it from analyticsadmin.properties.dataStreams.patch or delete without opening either schema.

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?

Clear operating context: irreversible removal, refused under --readonly safety profiles, and the sibling operations listed for contrast. It does not spell out an explicit 'use this when X, use patch when Y' decision rule, so it stops short of full routing guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden; it partially meets this by disclosing '[HTTP GET]' (read-only, no side effects) and that the response is the resource as JSON. It omits auth/permission requirements and rate-limit behavior, and the body_file/typed-parameter machinery is irrelevant noise for a GET.

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?

Front-loaded with the core purpose and a short sibling roster; it is reasonably tight. The request-body/body_file sentence is wasted on a GET endpoint, and the wording is slightly run-on.

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?

An output schema exists so return values need not be explained, and all five parameters are schema-documented. The description says what the tool does and returns, leaving only minor gaps (permissions, pagination not relevant here); the body_file mention is surplus but not harmful.

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 every parameter is already documented, giving a baseline of 3. The description restates the typed-flags-vs-params precedence and body_file behavior that the schema already explains, adding no new parameter semantics.

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?

States a specific verb+resource: 'Lookup for a single DataStream [HTTP GET]', and enumerates the sibling operations over the same resource (create, delete, list, patch), which helps an agent route away from mutations and the list. It stops short of a full five because 'lookup' is soft and the sibling list is generic boilerplate rather than a scoping distinction.

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 sibling enumeration implies 'this is the read-one of the family', but there is no explicit when-to-use versus the list method or when-not guidance. Nothing tells the agent to use list first to discover names, so usage is only implied.

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

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

With no annotations, the description does carry the read-only nature via 'Lists' and '[HTTP GET]', and mentions the JSON return. But the second sentence is generic transport boilerplate about request bodies and body_file that is largely irrelevant—and mildly misleading—for a GET list operation, and it omits any mention of pagination semantics, permissions, or rate limits beyond what the schema already states.

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 purpose clause is correctly front-loaded and short, but the second sentence is shared transport boilerplate (body building, body_file) that does not earn its place on a read-only list endpoint and dilutes the definition.

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?

An output schema exists, so return values need not be explained, and the schema fully covers all seven parameters including the required parent format. What remains thin is the behavioral envelope (pagination flow across pageToken, permission requirements), which keeps it short of a 5.

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 parent, pageSize, pageToken, query, params, dry_run and body_file in detail. The description adds no parameter-level meaning beyond restating the generic typed-parameter/params precedence rule, 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?

States a specific verb and resource ('Lists DataStreams on a property') and explicitly names the sibling operations (create, delete, get, patch) over the same resource, so an agent can separate this list operation from the single-resource get without inspecting schemas.

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?

Naming the sibling operations gives clear context for what this tool is not, and '[HTTP GET]' plus 'Lists' signals a read path. However, it never states explicitly when to choose list over get (e.g., enumerating all streams vs. fetching one by ID), so the exclusion is implied rather than spelled out.

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

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

No annotations, so the description carries the burden and does well: it marks this as an HTTP POST mutation, notes --readonly refusal, and describes the return as a JSON response resource. It omits auth/permission requirements and whether secretValue is only returned once, which for a secret-creating tool would be valuable caveats.

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?

Efficient and front-loaded with the action and safety note; the body/passing details and sibling list follow logically. Dense but each clause carries 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?

A mutation tool with no annotations and an output schema; the description covers action, safety refusal, body construction, and return type, which is adequate. Auth scopes and secret-value sensitivity are the notable omissions.

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%, so baseline is 3, but the description adds real value: it enumerates the body fields (displayName, name, secretValue) and clarifies the pass mechanism (via `params` or whole via `body_file`).

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?

States a specific verb and resource (creates a measurement protocol secret) and distinguishes it from siblings by naming the resource family (delete, get, list, patch). An agent can identify it without opening the schema.

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 discloses when the tool will be refused (--readonly safety profiles) and lists sibling operations over the same resource, which implies create-vs-read/edit routing. It doesn't explicitly say 'use get/list to read before creating', but the context is clear.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses irreversibility, read-only refusal behavior, that it returns the post-delete resource state (or empty) as JSON, and how the request body is constructed (typed params vs params map vs body_file). The hedge 'unless the API documents a trash/undo flow' introduces minor ambiguity about recoverability.

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?

Front-loaded with the verb+resource and HTTP method, then behavioral traits, then siblings. It is dense but every clause (irreversibility, readonly refusal, return shape, body construction) carries information; slightly crowded into a single flowing paragraph.

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 destructive operation with an output schema and 100% param coverage, the description adds the key non-structured context an agent needs: irreversibility, safety-profile refusal, and return shape. Complete enough to invoke correctly, with only the recoverability hedge as a minor gap.

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 name, query, params, dry_run, and body_file. The description only adds the typed-params-win precedence and body_file behavior, which is largely already in the schema descriptions. Baseline 3 is appropriate.

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?

States a specific verb (Deletes) and resource (MeasurementProtocolSecret) and names the HTTP method, then lists the siblings over the same resource (create, get, list, patch) so the agent can distinguish this from them without inspecting schemas.

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?

Provides clear usage context — refused under --readonly safety profiles and irreversible — and names the sibling operations. It stops short of explicit when-to-use/when-not versus a specific alternative (e.g., patch), so it falls just below a 5.

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

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

No annotations exist, so the description carries the full burden. It does disclose the operation is an HTTP GET returning the requested resource as JSON, which tells the agent it is a read. However, the trailing explanation about building request bodies from typed parameters or `body_file` is irrelevant for a GET (no body is sent) and risks confusing the agent, and there is no mention that the returned secret value is sensitive or what happens when the name does not resolve.

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 purpose is front-loaded and the whole definition is short, but the middle clause about request-body construction is dead weight for a pure GET and dilutes the message. Trimming that clause would leave a tighter, more accurate two-sentence definition.

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?

An output schema exists and the input schema is fully annotated, so the description does not need to explain return values or parameter formats. Given the tool's low complexity, the definition plus structured fields are nearly sufficient; only permission requirements and the sensitivity of the retrieved secret are left unstated.

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 `name` (with a regex and full resource-name format), `query`, `params`, `dry_run`, and `body_file`. The description's note that typed parameters win over the `params` map adds a small precedence clarification, but most of its parameter text restates what the schema already says; 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 a specific verb and resource ('Lookup for a single MeasurementProtocolSecret'), states the HTTP method, and explicitly lists the sibling operations (create, delete, list, patch) over the same resource, which lets an agent distinguish this from the list variant. It is not fully specific about what a 'secret' contains, but the resource identity is clear.

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?

Mentioning the sibling set implies this is the single-resource fetch versus the list operation, but the description never says explicitly when to prefer this over list or what prerequisites (e.g. needing the full resource name under a data stream) apply. Usage is inferable rather than stated.

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

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

No annotations are provided, so the description carries the safety burden; 'HTTP GET' signals a read-only retrieval and it states the result is JSON. It does not discuss authorization, rate limits, or pagination behavior beyond what the schema already documents, and the mention of body_file is not relevant to a GET list.

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 first sentence is appropriately front-loaded, but the second sentence's explanation of request-body construction from typed parameters or body_file is boilerplate that does not apply to a GET list operation. The sibling list is useful, but the body_file clause costs conciseness without adding value.

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 rich schema and an existing output schema, the description supplies the key missing orientation: resource, parent scope, verb, and sibling operations. It is sufficient to call correctly, although it omits explicit pagination guidance and auth/rate-limit notes that would matter more without annotations.

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 parent, pageSize, pageToken, dry_run, body_file, params, and query. The description only restates that typed flags override params and that body_file can supply a body, which adds no material meaning for this list call's parameters.

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 specific list operation for MeasurementProtocolSecrets under a parent Property and identifies the HTTP verb (GET). It also names the sibling create/delete/get/patch operations, which helps orientation, though the generic body-building sentence is irrelevant to a GET and slightly blurs the purpose.

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?

Naming the sibling operations implies this tool is the list variant, but the description never states when to choose it over get or the other siblings, nor any prerequisites. The agent is left to infer the distinction.

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

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

No annotations are provided, so the description carries the disclosure burden. It usefully states that this is an HTTP PATCH mutation, that it is refused under readonly safety profiles, and that it returns the API response resource as JSON; however, it does not explain permission requirements, reversibility, or other side effects beyond the basic safety-profile constraint.

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 front-loaded with the core action and resource, and it avoids unnecessary filler. It is somewhat dense as a single run-on sentence with several em-dash clauses, but the information is relevant and efficiently packed.

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?

The description covers the key facts needed to invoke this tool: it is an update/PATCH operation, it is blocked under readonly safety profiles, it returns the API response resource, and the body can be supplied via `params` or `body_file`. With a full output schema and 100% parameter schema coverage, the remaining gaps around permissions are not fatal, though they prevent a top score.

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 seven parameters in detail. The description mentions the request-body fields displayName, name, and secretValue and explains that the body may be passed via `params` or `body_file`, but this largely repeats what the schema already states rather than adding new semantic meaning.

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 gives a specific verb and resource: "Updates a measurement protocol secret", and identifies the HTTP method as PATCH. It also names the sibling operations over the same resource (create, delete, get, list), so an agent can distinguish this mutation tool from the read and creation alternatives.

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 clearly frames this as the update operation and explicitly notes that it is "refused under --readonly safety profiles", which is a useful when-not condition. It names the sibling operations as alternatives, though it does not give detailed selection criteria for choosing patch over those operations beyond the implied update/read/create/delete split.

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

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

With no annotations, the description carries the full burden. It discloses that the operation is refused under --readonly safety profiles, describes the return value (the API's response resource as JSON), and explains the request body structure and two submission methods (params or body_file). It does not mention permissions or rate limits, but these are minor gaps given the disclosure of the safety restriction.

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 front-loaded with the core action and resource, then packs in safety, return format, body structure, and sibling context in a single dense but waste-free sentence.

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 (mutation, nested request body, no annotations), the description covers the key procedural and behavioral points: safety profile refusal, return value, body handling, and sibling operations. It omits some details like updateMask semantics, but the schema covers those.

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 baseline is 3. The description repeats the request body field names and explains that the body can be passed via `params` or `body_file`, but this largely duplicates existing schema descriptions rather than adding significant new meaning.

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 specific verb ('Updates') and resource ('DataStream on a property') with HTTP method, and explicitly lists the sibling operations (create, delete, get, list) so an agent can distinguish it without opening the schema.

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?

By naming the sibling operations create/delete/get/list, it implies this tool is for partial updates rather than creation or retrieval. It does not explicitly state when to prefer patch over update or when not to use it, but the context is clear enough.

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

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

With no annotations, the description carries the full burden and largely meets it: it discloses that the delete is a soft-delete, that restoration is only possible through the UI, that child resources (GoogleAdsLinks, Streams, AccessBindings) are permanently purged after expiration, and that it errors when the target is missing. It lacks permission/authorization requirements, and the appended boilerplate about request bodies and --readonly profiles is generic filler that does not describe this tool's actual behavior.

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 core documentation paragraphs are front-loaded and substantive, but the tail contains fabricated CLI-style boilerplate ("[HTTP DELETE] — removes the resource", "request bodies are built from the typed parameters") that is irrelevant to a DELETE with no body and dilutes the useful content. The useful text could be half as long.

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 an output schema exists and annotations are absent, the description supplies the essential safety context: soft-delete semantics, irreversibility, child-resource purge, and the not-found error. It omits required permissions or scope, which an agent would need before attempting a destructive call.

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%, including a regex pattern and a format example for `name`, so the schema already documents the sole meaningful parameter. The description adds no conflicting or redundant parameter detail; the passing mention of `params` and `body_file` is generic boilerplate, not a claim about this call.

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 opening sentence names a specific verb and resource ("Marks target Property as soft-deleted (ie: 'trashed')") and states it returns the mutated resource. This distinguishes it from the siblings that also operate on a Property, such as patch, get, and acknowledgeUserDataCollection, because it is explicitly a trash operation rather than an update or read.

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 clear context for when this operation is called (trashing a Property) and warns that there is no API restore path, only the Trash Can UI. It does not contrast this with alternatives on the same resource (e.g., patch vs. delete), so the guidance covers the situation but not the decision between similar tools.

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

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

With no annotations provided, the description does substantial work: it declares the HTTP method (POST), flags that this creates or triggers a change, and uniquely discloses that the call is refused under --readonly safety profiles. It also states the return shape. It stops short of permission/scope requirements or error semantics, which is the remaining gap for an unannotated mutation tool.

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