Serpier

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses that this mutates state by adding a prompt and kicking off an analysis run, and it documents the failure contract: a `{ ok: false, error }` result means failure and should be surfaced rather than retried. It omits permission requirements, duplicate/idempotency behavior, and any cost implications of starting a run.

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 sentences, purpose front-loaded, followed by actionable failure guidance. No wasted wording, though the error-handling sentence is somewhat generic boilerplate.

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 reveals the error response shape despite no output schema, which helps, but for a mutation tool with nested parameters and a sibling that estimates setup cost, it leaves the agent unsure about cost, duplication, and how the "scoped analysis run" relates to create-llm-run.

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 only 50% and the description explains none of the four required parameters, including the nested `prompt` object with `prompt`, `languageCode`, `location`, and `funnelStage`. With half the schema undocumented and a nested structure, the description needed to compensate and does not.

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: adds one tracked AI Visibility prompt to monitoring and starts a scoped analysis run. The word "one" implicitly distinguishes it from the bulk sibling add-llm-prompts, though it never names that alternative explicitly.

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?

Implies a monitoring must already be configured ("to configured monitoring") and gives error-handling guidance (explain, ask user to help, don't retry blindly), but it never says when to pick this over add-llm-prompts or create-llm-run, nor what prerequisites exist.

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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write nature is covered. The description usefully adds deduplication ('already saved are skipped') and the side effect of triggering an analysis run, which annotations do not convey. However, it states the run unconditionally while the schema exposes an optional runAnalysisNow flag, creating ambiguity about whether the run is controllable.

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, front-loaded sentences with no filler: the action first, then the dedup and run side effects. Only the vague 'one analysis run' phrasing costs it a point.

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?

Annotations cover the safety profile and there is no output schema to explain, but with a nested prompt array, a required context/llm_model analytics pattern, and a 40% schema coverage, the description leaves real gaps. It says nothing about the analysis-run toggle or what the caller gets back when prompts are skipped.

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 only 40%, so the description must compensate and largely does not: runAnalysisNow, advertiserProjectId, and the prompt item fields (location, funnelStage, languageCode) are never explained. The description only gestures at 'prompts' and never clarifies that runAnalysisNow governs the analysis run it mentions.

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 ('Add tracked AI Visibility prompts') plus a scope distinction: existing prompts are skipped, so it reads as a bulk/upsert-style add. It does not explicitly say how it differs from the sibling 'add-llm-prompt', which an agent must infer from the plural name.

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 skip-if-already-saved behavior implies a safe 'just add what's new' context, but there is no explicit when-to-use guidance or reference to alternatives like add-llm-prompt or bulk-add-monitored-articles. The absence of any mention of runAnalysisNow also leaves the caller without a decision rule for that toggle.

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?

Annotations already declare the write-but-non-destructive profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds genuinely useful behavior beyond that: it defines the failure response shape `{ ok: false, error }` and prescribes an error-handling protocol (explain to user, help resolve, don't blindly retry), which annotations do not convey.

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?

Three sentences, front-loaded with the core action and followed by required inputs and the failure protocol. No filler, though the error-handling sentence is lengthy yet still 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?

For a 6-param mutation with no output schema, the description covers the required fields, the failure return shape, and a recovery protocol. The success return format and permission requirements remain unstated, a modest gap but reasonable given the annotations and error guidance.

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 only 33%, so the description must carry weight for the business params. It does list articleUrl, advertiserProjectId, anchorText and anchorRel, giving minimal meaning, but it doesn't explain semantics like the DOFOLLOW/NOFOLLOW/SPONSORED enum choices or the project ID reference. Partial compensation, not full.

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 (add a monitored article) and scopes it to 'monitored for changes.' It implicitly distinguishes from the sibling bulk-add-monitored-articles by describing a single URL, though it doesn't name the sibling explicitly.

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 implied by 'add a new article URL to be monitored,' and the mentions of advertiser project ID hint that a valid project must exist first. However, it never says when to use this versus bulk-add-monitored-articles or what prerequisites select a project, leaving the agent to 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?

Beyond annotations (readOnly=false, destructive=false, openWorld=false), it discloses two important traits: this tool may restore an existing soft-deleted project rather than always creating new, and it returns an `{ ok: false, error }` envelope on failure with explicit guidance not to blind-retry. It does not cover permissions or success-return shape.

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 purpose and only two sentences with no filler. The first sentence is a run-on (missing period between 'domain' and 'If this tool...'), which slightly hurts structure but not comprehension.

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?

Good handling of the failure path (error envelope, user-facing explanation) despite no output schema. It omits what a successful call returns (project object/id) and the domain input format, which matters for 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 67%: context and llm_model are well documented in the schema, but the critical `domain` parameter has no description anywhere. The description only says 'for a domain' and adds no format, validation, or scope meaning, leaving a real gap.

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+resource: create an advertiser project for a domain, or restore a soft-deleted one. It's clear, but it doesn't differentiate from siblings like get-project/get-projects (e.g., by telling the agent to check existing projects first).

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 implicitly frames when to use (create for a domain, restore soft-deleted) and gives failure-handling guidance (explain error, ask user to resolve, don't retry blindly). However, it never names alternatives or when-not-to-use conditions, e.g., checking get-projects first.

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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description earns credit for disclosing the duplicate-handling behavior ('left unchanged' when domain/publication type/project match), which is real idempotency context not present in the annotations; it stops short of auth requirements, batch/partial-failure behavior, or cart 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?

Two tight sentences with no filler, and the core action is front-loaded ahead of the dedupe nuance. Nothing is redundant.

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 described, and annotations cover the mutation profile. What's missing for a batch add-to-cart mutation is whether the whole call fails on one bad item, any cart-size limits, and how it relates to update-cart.

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 67%, with the top-level 'context' and 'llm_model' params fully documented in-schema. The description does add value by naming three of the item identity fields (domain, publication type, project) as the dedupe key, but contentTypeId and the ARTICLE/HOMEPAGE enum semantics go unexplained.

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 ('Add') and resource ('products to the shopping cart'), so the core action is unambiguous. The second sentence adds the dedupe key (domain, publication type, project), which further pins down what 'add' means, but the description never distinguishes this from the sibling update-cart.

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?

No explicit when-to-use / when-not-to-use guidance and no named alternatives. The 'left unchanged' clause implies this is the entry path for new cart entries rather than modification, but the agent must infer that update-cart is the tool for changing existing items.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the genuinely useful detail that prices are denominated in the organization's currency, which affects how an agent interprets salesPrice filters. It says nothing about result volume, pagination defaults or whether facets consume much of the response.

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?

Three short sentences, front-loaded with the purpose and no filler. It is efficient but borders on under-specification rather than tightness — there is room to add guidance without bloat.

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 10-parameter search tool with an output schema and two entirely undocumented parameters (strictAuthority, advertiserProjectId), three sentences are insufficient. An agent gets no guidance on what strictAuthority changes about matching behavior or what advertiserProjectId scopes, and those gaps are not covered elsewhere.

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 ~70% and the schema itself documents page, limit, search, filters and orderBy in depth with examples, so it carries most of the load. The description's one param-relevant contribution is the currency note for price filters; it says nothing about the two undocumented parameters (strictAuthority, advertiserProjectId) or about the mandatory context/llm_model analytics 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?

States a specific verb+resource: 'Search the publisher marketplace.' That is clear and distinguishable from add-to-cart, place-order and get-content-products siblings. It stops short of naming any sibling or defining scope boundaries (e.g. what marketplace listings are covered).

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?

'Filters, domain search, and sort are optional' implies the tool can be used as a plain paginated browse, which is useful. But there is no explicit when-to-use vs when-not-to-use guidance and no mention of alternatives such as get-content-products or add-to-cart for downstream actions.

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?

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: the failure response shape `{ ok: false, error }` and the instruction to surface the error rather than retry, which an agent could not infer from structured fields.

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?

Three sentences, front-loaded with the action and the per-row constraint, then the failure handling. The error-handling sentence is long but carries actionable instruction rather than filler.

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 bulk mutation with no output schema, the failure path is well covered, but the success return shape and atomicity are unaddressed: the description does not say whether a single bad row aborts the whole batch or whether valid rows are still added. That partial-failure behavior is the key unknown for a bulk 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 coverage is 67%, with context and llm_model already documented in-schema, but the article item fields carry no descriptions. The description compensates by clarifying that each row carries its own URL, project ID, anchor text and anchor rel and that these 'can differ per row' — a non-obvious semantic not encoded 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 and resource ('Add multiple publications to Publication Tracker') and the plural 'multiple' implicitly distinguishes it from the singular sibling add-monitored-article. It never names that sibling explicitly, so the differentiation is inferred rather than stated.

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 bulk framing implies when to use it, and there is useful recovery guidance for the failure path ('do not retry the same call blindly'), but there is no explicit statement of when to prefer this over add-monitored-article or what preconditions (valid project IDs, URL format) must hold before calling.

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?

Annotations declare destructiveHint=true and readOnlyHint=false, and the description is consistent with that (it is a mutation, not a run). But the annotations say the operation is destructive and the description never says what is destroyed: whether tagNames replace or append to existing tags, whether omitting funnelStage leaves it untouched, or whether the prompt set is overwritten wholesale. For a destructive batch mutation of up to 100 prompts, that omission is a real gap.

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 sentences, zero filler, and the core action is front-loaded before the scoping caveat. Nothing is repeated from the schema or annotations.

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?

Four required parameters, a nested object array, no output schema, and a destructive annotation — the description should carry more weight than two sentences. An agent still cannot tell whether tags merge or overwrite, what an empty/null funnelStage does, or what a partial failure across 100 prompts returns.

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 50% — context and llm_model are documented, but the nested prompts array (promptId, tagNames, funnelStage) has no descriptions at all. The description mentions "tags and funnel stage" generically but adds no semantics beyond what the schema already shows: it does not explain null funnelStage, tag replacement behavior, the 20-tag/50-char caps, or the 100-prompt batch limit.

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 pair ("Set tags and funnel stage") and a specific resource ("existing AI Visibility prompts"), which separates it from the add-llm-prompt / add-llm-prompts creation siblings. The negative clause "Does not start an analysis run" further rules out create-llm-run. It never names or distinguishes itself from the near-duplicate sibling set-prompt-funnel-stages, 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 word "existing" implies prompts must already exist, and "Does not start an analysis run" is an explicit when-not. However, no alternative is named, and given a sibling literally called set-prompt-funnel-stages, an agent has no stated basis for choosing between them — that is the single most important routing decision here.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavior: the `{ ok: false, error }` failure shape and an explicit instruction not to blindly retry, which matters for an irreversible bulk-delete. It does not state irreversibility or whether a confirmation step is expected.

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?

Three sentences, front-loaded with the core action, followed by the optional scoping and then error handling — no wasted text. The error-handling sentence is slightly procedural but earns its place given the destructive nature.

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 no output schema, the description usefully discloses the failure return shape, and it covers the scoping parameter and error-recovery path. The main omission for a destructive, no-confirmation tool is any statement about reversibility or what a successful response looks like.

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 67%, and the two analytics parameters (context, llm_model) are fully documented in the schema. The description supplies the missing semantics for `advertiserProjectId` by explaining it narrows the clear to one project, though it does not say where the ID comes from or its format.

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 ('Clear all items from the user's shopping cart') plus a narrower optional scope ('clear only items for a specific advertiser project'). This makes it unambiguous against siblings like add-to-cart, update-cart, and get-cart without needing to name them.

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 a clear conditional for the optional scoped variant and adds a runtime guideline (explain the error, ask the user to resolve, don't retry blindly). It stops short of naming alternatives such as update-cart for partial item changes, so it is clear context rather than full when/when-not 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 destructiveHint=true already declared, the description adds the crucial mitigation that only display lineage is rewritten and no new run is triggered, which materially changes how risky the call looks. It also discloses the failure contract (`{ ok: false, error }`) and the required user-facing behavior on error. It does not say whether the change is reversible or what permissions are needed.

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?

Three sentences, front-loaded with the operation and its side-effect scope before the error protocol. The final sentence is long but every clause (explain, ask user, don't retry) carries distinct instruction.

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 5-parameter mutation with no output schema, the definition covers purpose, side effect, error shape, and corrective action — enough to call it safely. Missing pieces are success-response shape and confirmation of what happens to dependent prompts/runs bound to the deprecated model.

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 only 40%, and the description never mentions advertiserProjectId, fromModelId, or toModelId by name. It does implicitly map 'deprecated model' → fromModelId and 'supported successor' → toModelId, which is real semantic value, but the project scoping parameter remains undocumented in both places.

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 and resource ('Convert a deprecated AI Visibility model on a project to a supported successor model') plus an explicit scope boundary ('Updates display lineage only; does not trigger a new run') that separates it from siblings like create-llm-run. An agent can tell exactly what state changes and what does not.

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?

Implies the trigger condition (a model is deprecated and must move to a supported successor) and gives explicit failure-handling guidance: explain the error, ask the user to resolve it, do not retry blindly. It stops short of naming an alternative tool (e.g. list-llm-models to discover successors) or stating prerequisites such as project permissions.

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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the failure return shape `{ ok: false, error }` and warning against blind retries. It does not mention cost, latency, or whether the run is async, which is the remaining gap.

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 sentence, with remediation guidance following. The error-handling sentence is slightly verbose with its parenthetical example, but each part earns its place by preventing a common misuse.

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?

There is no output schema, and the description covers only the failure return, not what a successful run returns (run ID, status, async behavior). For a non-destructive trigger tool whose annotations are already informative, this is adequate but leaves the agent guessing about success semantics.

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 67%, and the two documented parameters (context, llm_model) carry extensive descriptions that the prose does not need to repeat. The description's phrase "configured project" only loosely implies what advertiserProjectId should be, and that parameter is undocumented in both schema and description. 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?

The description states a specific verb and resource: manually re-running AI Visibility analysis over all saved prompts on a configured project. That scope is clear enough to separate it from configuration siblings like save-llm-config or get-llm-monitoring. It stops short of naming any sibling explicitly, so an agent must infer the boundary 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?

The word "Manually" signals the trigger condition (user-initiated run versus scheduled runs), and the second sentence gives concrete guidance on the failure path: explain the error and ask the user to resolve it rather than retrying. No explicit "when not to use" or named alternative is given, which keeps it out of 5 territory.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds valuable behavior the annotations cannot: the analysis-run blocking condition and the `{ ok: false, error }` failure shape. It never states whether the deletion is irreversible or what data is lost (config only vs. historical results), which matters for a destructive tool.

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?

Three short sentences, front-loaded with the action and its blocking condition, then failure handling. The error-handling sentence is somewhat boilerplate but earns its place by preventing blind retries.

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, no-output-schema tool, the description covers the precondition and error contract but omits irreversibility and the exact scope of deletion relative to llm_model. An agent could still call it correctly, but with a meaningful blind spot about consequences.

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 67% and two parameters have long inline descriptions, so the baseline is 3. The description only indirectly hints that advertiserProjectId is a project ID and says nothing about llm_model — leaving it ambiguous whether the delete is model-scoped or project-wide, which is the key semantic question here.

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?

"Delete AI Visibility monitoring for a project" gives a specific verb and resource, and the delete verb alone distinguishes it from read siblings like get-llm-monitoring and list-llm-monitorings. It does not explicitly name those siblings or clarify whether deletion is scoped to the given model or the whole project.

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 a real precondition ("Blocked while an analysis run is in progress") and post-failure guidance (explain the error, ask the user to fix it, don't blindly retry). It stops short of naming an alternative tool or the full set of conditions under which deletion should be chosen.

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?

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so safety is fully covered. The description adds nothing behavioral beyond that: no indication of whether the estimate is an approximation, what assumptions it makes about cadence, or how optional fields like modelIds/autoRunWeekdays affect the result.

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?

A single front-loaded sentence with no waste; the key inputs are enumerated immediately. It is arguably too terse for the parameter surface, but it is structurally efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 7 parameters (5 required), no output schema, and low schema coverage, the description should explain what the estimate returns (units, breakdown, whether it is per-model). None of that is present, so an agent cannot predict the response shape or the effect of several required parameters.

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 only 29% across 7 parameters, so the description must compensate. It does partially, by mapping 'prompt count', 'models', and 'cadence' to promptCount, modelIds, and autoRunFrequency, but it says nothing about advertiserProjectId, autoRunWeekdays, or how the frequency enum interacts with weekday selection.

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 (Estimate) and resource (Navi credit usage) and names the three drivers of the calculation (prompt count, models, cadence). It is clearly distinguishable from read/create siblings like get-llm-monitoring or create-llm-run, though it never explicitly contrasts itself with them.

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 gives no when-to-use context: no prerequisites, no note that this is a pre-purchase/pre-setup estimate rather than a post-hoc usage report, and no pointer to alternatives such as get-monitoring-stats for actual usage. Usage is only implied by the resource being 'setup cost'.

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?

Annotations already declare the destructive, non-readonly nature, lowering the bar. The description adds which fields get set, but omits what gets overwritten on existing publications, and says nothing about the advertiserProvided flags, guideline attachment, or the five contentInput variants. Useful but materially incomplete for a destructive 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?

A single, front-loaded sentence with no filler. It is efficient, though the brevity is partly what leaves coverage gaps elsewhere.

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 7-parameter destructive mutation with a nested anyOf parameter and no output schema, the description covers only the three simplest fields. It does not describe the contentInput branch selection, guideline attachment, or expected effects, which is a significant shortfall.

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 only 29%, so the description must compensate — and it only maps to contentInput.url, contentInput.anchor, and publishAt. It ignores publicationIds, orderGuidelines, attachedGuidelineTypes, and the entire multi-branch contentInput structure (googleDocsURL, keywords, topic, imageQuery, visibilityPrompts), leaving the agent to reverse-engineer the most complex parameter from the schema alone.

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 concrete verb ('Set') and concrete resources (target URL, anchor text, publication date) scoped to 'publications in an order,' which lets an agent distinguish it from siblings like place-order or get-order. It stops short of explicitly naming which sibling to prefer, so it lands at 4 rather than 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?

There is no statement of when to use this tool versus alternatives, no prerequisites, and no sequencing relative to place-order or update-cart. The agent must infer the workflow context from the tool name 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?

Annotations declare readOnlyHint=false and destructiveHint=true, which is counterintuitive for a 'get' tool; the description earns credit by explaining why — it 'may automatically correct stale content-product selections when a publisher's content requirements have changed' — so the mutation risk is disclosed. It also documents the failure envelope and error-handling contract. It does not say whether corrections are reversible or what side effects they carry.

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 primary purpose, then the mutation caveat, then the error-handling contract — a sensible order. Slightly long on error-handling prose for a read-mostly tool, but every sentence carries actionable content.

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?

No output schema exists, yet the description adequately describes the return shape (billing details presence, payment methods) and the failure shape ({ ok: false, error }). The main completeness gap is the undocumented discount/promo parameters, which leaves an agent guessing about capabilities the tool evidently has.

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 only 40%. The two required analytics parameters (context, llm_model) are documented in the schema, but promoCode, adminFixedDiscountName, and adminFixedDiscountAmount have no description anywhere, and the description never mentions them. It is genuinely surprising that a read-cart tool accepts admin discount amounts, and nothing explains when those should be supplied.

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 the current state of the user's shopping cart') plus the concrete contents returned (billing details presence, available payment methods). An agent can distinguish it from add-to-cart, update-cart, clear-cart, and get-order without inspecting 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?

Usage is implied (read cart state before checkout) and the description gives solid guidance on handling the `{ ok: false, error }` path, including an explicit 'do not retry blindly' exclusion. However, it never says when to prefer this over update-cart or get-order, nor any prerequisite ordering relative to place-order.

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?

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the error envelope shape (`{ ok: false, error }`) and a non-retry recovery procedure — behavioral detail an agent could not infer from structured fields. It stops short of describing the success payload (currency, pagination, how disabled or publication-type filtering affects results).

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 sentences, purpose front-loaded, with the error-handling clause clearly separated as conditional guidance. The second sentence is long but every clause carries actionable instruction (explain concisely, ask for help, don't blindly retry).

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 simple read-only listing tool with no output schema, the description covers the return subject (products and prices) and failure behavior. It is still incomplete on the two undocumented optional filters and on what a successful result contains, which matters because filtering directly changes the answer an agent reports to the user.

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 only 50%: context and llm_model are heavily documented, while includeDisabled and publicationType have no descriptions anywhere. The description mentions neither of these filters, so it does not compensate for the gap — notably it never states the default for includeDisabled or what ARTICLE_NOFOLLOW means in terms of returned products.

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?

"Get all available content products and their prices" gives a specific verb (get) and resource (content products + prices), so an agent can tell what it returns. It does not, however, distinguish itself from nearby siblings such as browse-marketplace or get-cart, which an agent could plausibly choose for similar catalog-pricing needs.

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 says what the tool returns but never states when to prefer it over browse-marketplace, get-cart, or get-order. The only guidance given is failure recovery, not tool selection or prerequisites (e.g. whether a project context is required for prices to resolve).

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it documents the failure envelope (`{ ok: false, error }`) and instructs the agent to surface the error to the user rather than retry blindly. It says nothing about result size, pagination, or cost, which keeps it below 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?

Two sentences, front-loaded with the capability statement, and the error-handling clause follows the read contract. Slightly long but every clause carries information; no filler or restatement of the name.

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 no output schema, the description usefully names the metrics returned, and it covers the failure mode. But for an 11-parameter filtered analytics query at 18% schema coverage, an agent is left guessing about date-range semantics, filter defaults, and result granularity — gaps the description should have closed.

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 only 18% across 11 parameters, so the description must compensate and largely does not. It never explains from/to, tagIds, funnelStages, languageCodes, sourceTypes, locations, or modelIds; only the words 'per-stage' and 'prompt mix' faintly gesture at funnelStages and modelIds. The two required analytics parameters (context, llm_model) are documented only 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 and resource ('Read per-stage funnel performance across AI Visibility and SEO for a project') and enumerates the metrics returned: prompt mix, visibility, share of voice, keyword counts, ranks. That is far more specific than the sibling tools (which mostly cover monitoring, prompts, cart/orders), but it never names a sibling or a boundary, so the differentiation is left implicit.

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 second sentence gives error-recovery guidance, but there is no statement of when to call this versus the near-neighbors like get-monitoring-stats, get-llm-monitoring, or get-llm-prompt. An agent cannot tell from the description what question this tool answers that those do not.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine value by disclosing the returned dataset (topics, models, cadence, saved prompts, latest run status, credit usage), which matters because no output schema exists. It stops short of noting behavior when monitoring isn't configured or any permission prerequisites.

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?

A single front-loaded sentence with no filler; the returned-field enumeration carries real information. It reads as a dense run-on list rather than a structured statement, but no sentence is wasted.

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 read-only getter with annotations covering the safety profile and no output schema, the description does a fair job by naming the returned fields. However, it leaves the key ambiguity against 'list-llm-monitorings' unresolved and says nothing about the undocumented 'advertiserProjectId', so an agent still has gaps to close.

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 67%: 'context' and 'llm_model' are heavily documented in the schema, while 'advertiserProjectId' has no description at all. The phrase 'for a project' loosely maps to that undocumented ID parameter but adds no format or sourcing detail, so the description only marginally compensates for the gap.

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 ('Get') and resource ('AI Visibility monitoring for a project') and enumerates the concrete payload: topics, models, cadence, saved prompts, latest run status, credit usage. An agent can tell what it retrieves, but the description never distinguishes it from the sibling 'list-llm-monitorings' or 'get-monitoring-stats', so the boundary remains fuzzy.

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 when-to-use guidance and no named alternative. With 'list-llm-monitorings' and 'get-monitoring-stats' in the sibling set, the agent is left to guess whether this is the single-project read or the enumeration call.

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?

Annotations already cover the read-only, non-destructive, closed-world profile, yet the description adds substantial beyond-schema behavior: downsampling to a maximum of 26 points, model omission under half its answers, the historyWindow shortening flag, competitorLimit default and cap, and the precise definition of visibility vs. share of voice. It also specifies the `{ ok: false, error }` failure shape and instructs the agent not to blindly retry, which is exactly the operational context annotations cannot convey.

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 output-semantics content is front-loaded and useful, but the description is dense and runs long, blending return-shape definitions, metric caveats, and error-handling instructions into a single block. Sentences like the one about recommendation criteria and factual errors being read from answer text are tangential to invoking the tool correctly.

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?

There is no output schema and the tool is complex, so the description carries the return-value burden itself — and does: it names the history, promptHistory, and historyWindow fields and explains downsampling and omission rules. Combined with the documented error path, an agent has everything needed to call and interpret the result.

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 only 60%, and the description compensates usefully: it explains promptId's origin (get-llm-monitoring config.prompts[].id) and clarifies competitorLimit semantics ('keep more than the default 4'). advertiserProjectId and the two analytics parameters are left to the schema, but the agent-critical parameters are covered.

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 scope: 'Get one saved prompt's scores across completed monitoring runs, oldest first.' The agent can distinguish this retrieval tool from siblings like get-llm-monitoring (config) and get-llm-prompt-suggestions because the description explicitly points to get-llm-monitoring as the source of promptId.

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 an explicit trigger: 'Use this when the user asks how a prompt is trending or progressing,' and routes the agent to get-llm-monitoring for obtaining promptId. It lacks explicit when-not guidance or a named alternative for adjacent tasks (e.g., config vs. history), so it stops short of 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: the `{ ok: false, error }` failure shape and the instruction not to retry blindly. However, it stays silent on the mutation-flavored parameters it accepts (replaceExisting, keptPrompts) and on what a successful response contains, which matters given no output schema.

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 sentences, front-loaded with the purpose and no filler. The second sentence is long but each clause (explain plainly, ask the user, don't retry) carries actionable instruction.

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 purpose and the failure path, which is more than many tools do. But with 11 parameters at 18% schema coverage and no output schema, key semantics — generation volume, funnel mixing, prompt replacement, language — are left entirely undocumented.

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 only 18% across 11 parameters, and the description mentions none of them. Nothing explains topics vs promptsPerTopic vs limit, the funnelMix object, keptPrompts, or what replaceExisting changes — the agent must infer all of this from bare property names. Only the 'select a valid project' aside hints at advertiserProjectId.

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 ('Generate suggested user-style prompts') and scopes it to 'AI Visibility monitoring based on selected topics and project context'. It is distinguishable from siblings like add-llm-prompt or classify-llm-prompts, though it never names an alternative to sharpen the boundary with get-llm-prompt-task-suggestions.

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 only implied by the phrase 'based on selected topics and project context'; there is no statement of when to call this versus add-llm-prompts or get-llm-prompt-task-suggestions, nor prerequisites such as needing an existing project. The error-handling sentence does give useful reactive guidance (explain the error, ask the user, don't blindly retry) but that is post-failure behavior, not invocation 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?

Annotations already declare readOnlyHint true and destructiveHint false, so the safety profile is covered. The description adds real behavioral value: it discloses that queued items not yet in the inbox are included, details the return contents and ordering, and explains the failure shape and recovery step.

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 purpose and return contents, then the sibling routing, then error handling. Slightly long but every sentence carries information; the error-handling sentence is a touch verbose.

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 no output schema, the description carries the return-shape burden and does so well by enumerating prompts, topic, task id/sequence, content recommendation, and publisher shortlist. Only minor gap is the unexplained advertiserProjectId parameter.

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 67%; the two analytics params (context, llm_model) are documented in-schema. The advertiserProjectId has only a pattern and no description, and the description only weakly implies it via 'the active project.' Baseline 3 given the partial coverage.

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: 'List open publisher-order suggestions for the active project from the suggestion engine,' with the added detail of including queued items. Clear what it does, but it does not distinguish itself from the sibling get-llm-prompt-suggestions, which shares nearly the same name.

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?

Routes link-fix and site-fix suggestions to get-suggestion-inbox and adds recovery guidance for the error case. However, it never addresses the closest-named sibling get-llm-prompt-suggestions, leaving the primary ambiguity unresolved.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that by disclosing the failure envelope shape (`{ ok: false, error }`) and a specific recovery protocol — tell the user, don't blind-retry — which the agent would otherwise not know.

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 purpose is front-loaded in the first clause, with the error-handling note following. Both sentences carry information and there is no filler, though the run-on first sentence would read better split.

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 seven parameters, 29% schema coverage, and no output schema, the description leaves the response shape and the filtering/pagination model entirely unexplained. The error-handling contract is a useful addition, but an agent still cannot predict what a monitored article contains or how filters map to results.

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 only 29%: only `context` and `llm_model` are documented, while `page`, `limit`, `search`, `filters`, and `orderBy` carry no schema descriptions. The description compensates for none of this — it never mentions pagination, search, filter, or sort behavior, so an agent must infer the semantics of five parameters entirely on its own.

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 organizational scope: 'Get all monitored articles for the organization.' The intent is immediately legible, but it does not distinguish itself from nearby siblings such as get-monitoring-stats or list-llm-monitorings, leaving the agent to infer which retrieval surface returns what.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to call this versus alternatives like get-monitoring-stats, get-llm-monitoring, or list-llm-monitorings, nor any stated prerequisites beyond the implied org scope. The only conditional guidance is about error recovery, not tool selection.

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?

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false, destructiveHint=false), so the bar is lower. The description earns credit for disclosing the failure contract — a `{ ok: false, error }` shape and an explicit no-blind-retry policy — but says nothing about scope of the counts (time window, per-project vs org-wide) or pagination.

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 sentences, front-loaded with the purpose before the error-handling clause. Every sentence carries content; the only minor cost is that the failure-recovery instruction occupies roughly half the text relative to the short capability statement.

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 no output schema, the description compensates by naming what comes back (total monitored articles, changes detected) and how failures are shaped. For a two-parameter read-only tool whose parameters are fully schematized, nothing an agent needs to call it correctly 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 description coverage is 100%, so both required parameters (`context`, `llm_model`) are fully documented in the schema, making baseline 3 correct. The description adds no parameter information at all — notably it never signals that two mandatory analytics parameters must be supplied.

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 clear verb and resource — 'Get monitoring statistics for the organization' — and enumerates the contents (total monitored articles, changes detected). It does not, however, distinguish itself from monitoring-adjacent siblings such as get-llm-monitoring, list-llm-monitorings, or get-monitored-articles, so an agent still has to infer which 'monitoring' this covers.

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 conditional guidance is about failure handling ('do not retry the same call blindly'), which is post-call behavior, not selection guidance. Nothing says when to pick this over get-monitored-articles or get-llm-monitoring, and no prerequisites are 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one useful return detail ("including its publication ids"), but says nothing about what happens with an invalid or missing id, nor about the shape of the response.

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?

A single front-loaded sentence with zero filler; the identifier-based lookup and the notable return field are both delivered immediately.

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?

There is no output schema, so the description carries some burden for return shape, and it only partially meets it by mentioning publication ids. For a simple read lookup that is close to adequate, but an agent gets no information about error cases or what else an order contains.

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 67% and the two analytics parameters (context, llm_model) are heavily documented in the schema. The description only clarifies that `id` identifies the order and notes publication ids appear in the result; it adds no format or constraint detail beyond that, so the baseline of 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 ("Get one order by id") and signals the singular scope, which implicitly contrasts with the sibling get-orders. It does not explicitly name a sibling or state the contrast, so it stops short of 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 phrase "by id" implies this is a direct lookup when the order identifier is known, but there is no explicit when-to-use/when-not, no mention of get-orders as the alternative, and no prerequisites. 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?

Annotations already declare readOnlyHint/not-destructive, so the safety profile is covered. The description adds valuable behavioral context by explaining the `{ ok: false, error }` failure contract and instructing the agent not to blindly retry, which annotations don't convey.

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, then the filter mechanics, then error handling – a sensible order. A couple of clauses on operators are somewhat redundant with the filter sub-schema descriptions, but overall it is tight and earns its space.

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 an 8-parameter list tool with no output schema, the description covers filters and error handling but omits pagination (page/limit), search, orderBy, and organization scoping. These gaps leave the agent guessing on several non-trivial parameters.

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 low (38%), but the description compensates well for the most complex parameter, `filters`, detailing columnId values, type, operators, AND semantics, and ISO date format with 'is between'. It leaves page, limit, search, orderBy, and organizationId undocumented, so it isn't fully complete.

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 orders for the organization'), making the operation clear. It doesn't differentiate from the singular 'get-order' sibling, so an agent must infer that this returns a list while the other fetches one.

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 detailed guidance on how to build filters (AND combination, 'is any of', date ranges), but never addresses when to choose this tool over 'get-order' or other siblings. Usage is implied rather than explicitly scoped against alternatives.

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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered for free. The description's added value is the return field list (id, name, color), useful given there is no output schema, but it says nothing about ordering, volume limits, or whether all org tags are returned at once.

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?

A single front-loaded sentence with no filler. The resource is named first and the returned fields follow immediately.

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 no-parameter, read-only list tool with no output schema, the description supplies the essential return shape, which is the main thing an agent needs. Minor gaps remain around pagination or result limits, but nothing blocking.

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 both parameters (context, llm_model) are analytics-only plumbing rather than functional inputs, so the schema already carries their semantics. The description adds no parameter information, but the baseline 3 applies since there is nothing functional for it to explain.

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 ('List') plus resource ('this organization's tags'), and it names the returned fields (id, name, color). No sibling in the toolset covers tags, so there is no real ambiguity to disambiguate against, which keeps it just below 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?

Implicit usage only: an agent can infer this is the read path for tag data, and 'this organization' scopes it to the current org context. The description never states when to call it, what triggers it, or what a caller should do instead if they need cross-org or filtered tag data.

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?

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds a real behavioral contract beyond them: the `{ ok: false, error }` failure shape and an instruction not to retry blindly. It does not describe the success payload, but no output schema exists so that gap is modest.

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 capability is front-loaded in the first sentence and the error-handling note follows as a secondary paragraph. The error sentence is somewhat verbose for what it conveys, but every part carries actionable 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?

For a read-only lookup with annotations and no output schema, the description covers purpose, failure semantics, and error recovery well. However, with two of four parameters lacking schema documentation and no stated relationship between ID and domain lookup, an agent could not confidently determine which key to supply.

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 50% — context and llm_model are documented, while domain and advertiserProjectId have no schema descriptions. The description partially compensates by clarifying that domain accepts a URL form and that ID is an alternative key, but it says nothing about precedence, mutual exclusivity, or fallback behavior, so the undocumented parameters remain underspecified.

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 advertiser project details') plus the two lookup keys (project ID or domain/URL) and the organizational scope. It is clearly distinct from get-projects in intent, though the description never names that sibling explicitly.

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 two accepted lookup modes imply when the tool applies, but there is no explicit guidance on choosing this over get-projects, nor whether one of advertiserProjectId/domain is required or what happens if both are supplied. Usage is inferred 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?

Annotations already declare readOnly, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new behavior: the failure shape `{ ok: false, error }` and an instruction not to retry blindly — useful operational guidance beyond the structured fields. It omits any mention of pagination behavior despite a `page` parameter.

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 purpose sentence followed by a focused failure-handling note; no filler. Minor flaw: the two sentences run together ("...for the user If this tool returns") and the error paragraph is slightly long for its payload.

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 no output schema and 4 parameters at 50% coverage, the description should explain result shape and pagination, and it does neither. The error-handling guidance is a plus, but an agent still lacks enough to call it correctly with `search` or `page`.

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 only 50%: `context` and `llm_model` are well documented, but `page` and `search` have no schema descriptions and the description does not compensate — it says "Get all" projects with no hint that results can be filtered or paged. This gap could lead an agent to assume a single unfiltered list.

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 all advertiser projects for the user"), so the operation is unambiguous. It does not distinguish itself from the singular sibling `get-project`, leaving the agent to guess whether this is a list endpoint or a duplicate.

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?

No guidance on when to use this versus `get-project` or any other sibling, and no prerequisites stated. The only implied usage cue is the phrase "for the user", which is too weak to route an agent between alternatives.

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?

Annotations already cover read-only, non-destructive, closed-world, so the bar is lower, but the description still adds real value: it discloses the return payload contents (provider labels, cost tiers) and, importantly, that failures come back as `{ ok: false, error }` rather than throwing, with instructions not to retry blindly. That error-envelope behavior is not derivable from the annotations or schema.

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 is front-loaded in the first sentence; the error-handling guidance follows in a compact second and third sentence. The error guidance is somewhat verbose but earns its place because the failure mode is otherwise undocumented.

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 no output schema, the description carries the burden of describing returns and does so at a high level (models, provider labels, cost tiers) plus the error shape. It leaves out list ordering/pagination and whether models are filtered by plan quota, but nothing that would cause a mis-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 description coverage is 100% and both parameters (`context`, `llm_model`) are documented at length in the schema itself. The description adds nothing about parameters, 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 ('List available AI Visibility LLM models') plus scope ('for the organization's plan') and return content ('provider labels and cost tiers'). It is clearly distinguishable from siblings like convert-llm-model or create-llm-run, though the description never names an alternative explicitly.

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 statement of when to call this versus alternatives (e.g. before convert-llm-model or estimate-llm-setup-cost) and no preconditions beyond 'the organization's plan'. Usage is only implied by the resource name; an agent must infer the call site.

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?

Annotations already establish readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the failure contract — a `{ ok: false, error }` return — and telling the agent how to respond (explain plainly, request user help, do not blindly retry). Return buckets are also sketched, though pagination/ordering behavior is not addressed.

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 sentences, both earning their place: the first front-loads what is returned, the second covers the failure path. No filler, no restatement of the title, and the most decision-relevant information (the three buckets) comes first.

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 no output schema present, the description does its job by naming what comes back (monitored projects with metrics, unmonitored projects, limits) and how to handle the error envelope. Missing only minor detail such as result ordering or whether large orgs paginate, which is a small gap for a low-complexity 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?

Both parameters are fully documented in the schema (100% coverage), including the unusual `context` and `llm_model` analytics fields, so the schema carries the load. The description adds nothing about either parameter. Baseline 3 applies when schema coverage is complete and the description stays silent on params.

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 first sentence gives a specific verb ('List') and resource ('AI Visibility monitoring for the organization') and enumerates the three result buckets: configured projects with metrics, projects without monitoring, and org prompt/project limits. That makes the scope distinguishable from get-monitoring-stats or the singular get-llm-monitoring. It stops short of naming those siblings explicitly, so the contrast is inferable rather than stated.

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 implied by 'for the organization' — call this to get the org-wide inventory — but there is no explicit statement of when to prefer it over get-llm-monitoring or get-monitoring-stats. The error-handling instruction ('ask them to help resolve it... do not retry') is genuinely useful operational guidance, though it governs failure behavior rather than tool selection.

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?

Annotations already declare it is not read-only and not destructive, so the safety profile is known. The description adds no behavioral context such as Stripe account prerequisites, link expiration, single-use behavior, or what returnPath controls.

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?

One short, front-loaded sentence with no wasted words. It efficiently conveys the core action and target system.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool that creates an external billing portal link and has no output schema, the description does not explain what is returned (e.g., a URL), whether the link should be presented to the user, or how returnPath affects behavior. It is too thin for an integration with financial/billing implications.

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 moderate at 67%; the meta parameters context and llm_model are well documented, but returnPath is only given a type and default with no semantic description. The tool description mentions no parameters at all, so it does not compensate for this gap.

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 ('Create a link') and resource ('Stripe billing portal') with scope ('this organization's payment details'). The purpose is clear, though it does not explicitly differentiate from any sibling tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The use case is implied: when an organization needs to manage payment details via Stripe. However, there is no explicit when-to-use, when-not-to-use, or alternative 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?

Annotations already flag this as a non-read-only, destructive mutation, so the description doesn't owe a safety warning. It does add real behavioral value by disclosing the two possible outcomes (order id vs. Stripe checkout URL when card payment is required), which matters because there is no output schema. It stays silent, however, on irreversibility, permission needs, and side effects like applying discounts or ordering on behalf of another user.

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, front-loaded with the action and then the outcome. Nothing is padding; every 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?

For a destructive 10-parameter purchase tool with no output schema, the description is far too thin. It never explains the parameters that drive behaviour (payment method, discounts, ordering for another user), nor the prerequisites, and does not compensate for the 20% schema description 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 coverage is only 20% across 10 parameters, so the description carries the burden and does not meet it: offerId, offerRecipientId, orderForUserId, PONumber, promoCode, paymentMethod (stripe/invoice) and the adminFixedDiscount fields go entirely unmentioned. The only hint at a parameter is the reference to card payment, which loosely maps to the paymentMethod enum.

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?

A specific verb and resource ("Place an order from the current cart") plus a statement of what is returned. It is unmistakable from read-oriented siblings such as get-cart, get-order and get-orders, though it never names a sibling or notes what edge cases call for update-cart/fill-order-details first.

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 implied usage cue is "from the current cart", i.e. the cart must already be filled. There is no statement of when to prefer this over get-order/get-orders, when a prerequisite step is required, or how paymentMethod/discount choices should be made.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is covered. The description adds one genuinely new behavioral fact — that no analysis run is triggered — but omits irreversibility, whether associated data is purged, and permission requirements.

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 zero filler; the scope comes first and the behavioral caveat follows. Nothing is padded.

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?

This is a destructive, 4-required-parameter mutation with no output schema, yet the description never states what happens on success, whether removal is reversible, or how the project/prompt pair is scoped. Half the parameters are undocumented, so an agent lacks what it needs to call this confidently.

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 50%: context and llm_model are fully documented in the schema, but promptId and advertiserProjectId have no description anywhere. The description only implies promptId via 'one tracked ... prompt' and says nothing about advertiserProjectId scoping, so it fails to compensate for the gap.

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 ('Remove one tracked AI Visibility prompt'), and 'one' distinguishes it from bulk siblings. It doesn't explicitly name add-llm-prompt or delete-llm-monitoring as the alternatives, but the scope is unambiguous.

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?

'Does not start an analysis run' is a useful conditional hint about consequences, implying this is a cleanup action separate from create-llm-run. However, there is no explicit guidance on when to choose this over delete-llm-monitoring or how it relates to the add-* siblings.

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?

Annotations declare destructiveHint=true and readOnlyHint=false, so the agent knows this mutates. The description adds useful scoping context ('initial setup') but never discloses what the destructive behavior actually is — whether it overwrites an existing configuration, replaces topics/prompts, or is irreversible. That is the most important thing to know here and it is left implicit.

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?

One front-loaded sentence with no filler; the scoping phrase 'on initial setup' is placed at the end where it belongs. It is efficient, though it is arguably too short for a 13-parameter destructive tool.

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 13 parameters at 15% description coverage, a destructive mutation hint, and no output schema, the definition needs considerably more: what the save replaces, required vs optional parameter intent, and how cadence enumerations interact with autoRunWeekdays. As written, an agent could call it correctly only by reading the schema closely.

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?

Only 15% schema description coverage across 13 parameters, so the description carries the burden and covers just 4 concepts (topics, models, cadence, prompts). The remaining parameters — funnelMix, pinned/hiddenCompetitorDomains, defaultLocation, runFirstAnalysisNow, autoRunWeekdays, advertiserProjectId — get no mention or explanation. The description does not compensate for the low coverage.

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 (Save) and resource (AI Visibility monitoring settings) and enumerates the facets it covers: topics, models, cadence, and prompts. It also scopes the action to 'initial setup,' which separates it from read-oriented siblings like get-llm-monitoring. It does not, however, explicitly name a sibling it is not.

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 phrase 'on initial setup' implies when this tool is appropriate, distinguishing first-time configuration from later reads or deletions. But no alternative is named and no exclusion (e.g., 'use update-llm-monitoring to change existing settings' or 'use add-llm-prompt for single prompt additions') is given, so 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?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is carried. The description adds the useful 'clear' semantic (passing null resets rather than mutates), but says nothing about the 100-prompt bulk limit, permissions, or reversibility that a destructive tool should surface.

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?

A single, front-loaded sentence with no filler. Efficient, though arguably too terse for a five-required-parameter destructive bulk operation.

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 5-param, all-required, bulk, destructive mutation with no output schema, the description leaves too much unsaid: what clearing does to analytics history, whether setting is idempotent, and what a successful call returns.

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 40%, and the two documented params (context, llm_model) are analytics-only boilerplate. The description's 'set or clear' does usefully imply that funnelStage accepts null to clear, but it says nothing about promptIds (up to 100) or advertiserProjectId.

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 ('set or clear'), a specific attribute ('funnel stage'), and the resource ('tracked AI Visibility prompts'). Distinguishable from siblings, but it never names an alternative like classify-llm-prompts to clarify when funnel staging differs from classification.

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?

No when-to-use guidance, no prerequisites (e.g. project ownership), and no alternatives named. The 'or clear' hints at a negative case but doesn't say when an agent should clear versus set.

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?

Annotations already declare destructiveHint=true, so the safety profile is partly covered. However, the description does not disclose whether the items array replaces the entire cart or merges into it — a critical distinction when a partial list is sent against a destructive update. That replacement semantics gap is not filled anywhere else.

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?

A single front-loaded sentence with no filler. It is efficient, though its brevity is also the source of the missing replace-versus-merge semantics rather than a separate weakness.

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 cart mutation with no output schema, the description should state replacement behavior and item-matching rules. It provides neither, so an agent can call it but cannot predict the effect of a partial items array.

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 67% and the two documented parameters (context, llm_model) are fully explained there. The description touches contentTypeId implicitly, but says nothing about the 'items' array: whether it is a full replacement list, how item 'id' is matched to existing cart items, or what happens to items omitted from the list. That gap sits on the most consequential parameter.

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+resource ('Update cart items') and names the field being changed ('the content product selected for each item'), which maps to contentTypeId. It does not distinguish the tool from siblings like add-to-cart, clear-cart, or get-cart, so an agent must infer the difference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this rather than add-to-cart, remove-from-cart, or clear-cart, nor any mention of prerequisites such as an existing cart or item IDs. The agent is left to infer the correct routing from the name alone.

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