More Good Reviews

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so safety is covered. The description goes beyond them by disclosing the concrete destructive side effect that matters most here: unsent outreach messages are cancelled. It stops short of stating whether archiving is reversible, which is notable given an unarchiveCustomer sibling exists.

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?

Very short and front-loaded, with the side effect stated immediately after the action. The only waste is the verbatim repetition of the title 'Archive Customer' as a heading before the actual sentence.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety profile. Purpose plus side effect plus the rich structured fields make this largely complete; the missing piece is the archive/delete/reverse boundary against the many customer siblings.

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 the single id parameter is fully documented in the schema, so the baseline is 3. The description adds nothing about the identifier (e.g. where to obtain it or whether it accepts the numeric id only).

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 (archive) and resource (customer) plus a concrete side effect (cancels unsent outreach messages), which clearly separates it from a plain delete. It never names the relevant siblings (deleteCustomer, unarchiveCustomer), so the agent must infer the boundary between archiving and deleting.

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 archive versus deleteCustomer or when to use the sibling unarchiveCustomer to reverse it. The description only asserts what the tool does, leaving tool selection to inference from the names.

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, idempotentHint=true, and openWorldHint=true. The description adds meaningful value beyond that by specifying exactly what is destroyed ('scheduled outreach' / unsent messages) and what is left untouched (archiving, subscription state), which bounds the blast radius an agent should expect.

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?

Short and front-loaded, with the scope-limiting clause carrying the important information. The only waste is the first line restating the title verbatim, which is already provided in the title field.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description supplies the scoping constraint needed to invoke it correctly; only a pointer to the archive/unsubscribe alternatives 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%, with the single 'id' parameter fully documented as the customer's numeric identifier, so the schema does the heavy lifting. The description only implies the id refers to 'this customer' and adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (cancel customer unsent messages) and clarifies scope with 'Clear scheduled outreach for this customer.' It explicitly excludes archiving and subscription-state changes, which helps distinguish it from siblings like archiveCustomer and unsubscribeCustomer, though it names no sibling directly.

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 clause 'without archiving or changing subscription state' gives clear context for when this tool is the right choice versus the neighboring archive/unsubscribe tools. It stops short of explicitly naming those alternatives or stating prerequisites, 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?

The description adds the useful nuance that this is a record-keeping/ingestion event rather than a payment-capture operation, which goes beyond the annotations' write flags. It does not, however, describe side effects or failure behavior; since the annotations already carry the core write semantics, the gap is moderate rather than severe.

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 substantive description is a single efficient sentence, front-loading the action and source. The only waste is repeating 'Create Charge' before that sentence, so it earns a 4 rather than a 5.

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

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

Given the rich input schema, complete parameter descriptions, annotations, and an output schema, the description doesn't need to explain return values or parameter formats. It is complete enough for an agent to select and invoke the tool, though it omits deeper business rules such as whether the customer must already exist.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema fully documents each parameter. The description adds no parameter-level meaning beyond the general 'revenue event' framing, which keeps it at the baseline for fully covered schemas.

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 uses a specific verb ('Record') and resource ('customer revenue event') and adds the source system ('external billing system'), which clearly communicates what createCharge does. It doesn't explicitly name sibling tools, but the create/delete/list charge sibling set is easily distinguished by the verb and domain.

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 'from an external billing system' provides clear context for when this tool is appropriate: ingesting revenue events that occurred outside the system. It doesn't give explicit exclusions or name alternative tools, but the context is specific enough to prevent confusion with customer creation or charge listing/deletion.

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, idempotentHint=false, and openWorldHint=true, so the safety bar is lower. The description adds real value beyond them: it explains that matched rows are updated rather than created, and surfaces the 409 conflict when email and phone match two different customers. It does not disclose whether omitted fields are cleared on an update, 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?

Four short sentences, all load-bearing, with the upsert identity and match order front-loaded. No repetition of the title or schema 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?

With an output schema present, return values need no explanation, and the description covers matching, creation-vs-update, and the 409 path. The remaining gap is that a 15-parameter destructive upsert never says whether unspecified fields are nulled on an existing match.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description goes further by synthesizing the cross-field matching precedence (email first, then phone E.164, then raw) into a single rule, which is exactly the interaction the per-field schema docs describe only in isolation.

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 and resource ('Create or Update Customer' / 'Upsert a customer by contact identity') and immediately distinguishes itself from siblings like updateCustomer and getCustomer by framing the operation as an identity-matched upsert. An agent can tell what this does without opening the schema.

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

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

Gives clear operational context: when both email and phone are sent, email is tried first and phone is the fallback; single-field inputs use only that field. It does not explicitly name an alternative tool (e.g., updateCustomer) or state when to prefer this over a direct update, so it stops short of 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?

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the mutation/safety profile is covered by structured data. The description adds one real behavioral fact not in the annotations — that hosted pages are synced as a side effect — but says nothing about overwriting an existing icon or auth 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 compact sentences with the action front-loaded and the side effect in second position; nothing is padded. The only waste is the leading repeat of the tool title 'Create Icon' before the substantive sentence.

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

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

An output schema exists, so return values need no explanation, and the single parameter is fully documented. What is missing for a mutation tool is whether calling it replaces an existing icon, who may call it, and how it relates to the near-identical createLogo — leaving the agent without enough to choose 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 description coverage is 100%: the single 'url' parameter already documents accepted formats, the 5MB cap, the 100–2000 pixel bounds, and the 400 error condition. The description's phrase 'public square image' is consistent but adds no syntax or constraint beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Create Icon') and adds genuine scope: store a public square image as the project icon. It stops short of distinguishing itself from the very similar sibling createLogo (and createReviewShareImage), so an agent must guess which image-upload tool applies to which artifact.

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, no prerequisite statement, and no mention of the alternatives among the many image-creation siblings (createLogo, createReviewShareImage). The only hint is the noun 'project icon', which is implied context rather than explicit routing.

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 idempotentHint=false, so the description does not need to repeat safety traits. However, it adds no additional behavioral context such as side effects, permissions, or response behavior. There is no contradiction with the annotations.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short and the meaningful sentence is front-loaded. The opening line 'Create Location' is redundant with the title, but the rest is concise and free of 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?

Given the rich input schema, annotations, and output schema, the description is adequate for an agent to understand the tool's purpose. It does not cover alternative selection or prerequisites, but those are not essential for a straightforward create operation.

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%, with all nine parameters documented in the input schema. The description itself adds no parameter-level meaning, so it correctly relies on the schema. This meets the baseline but does not go beyond it.

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 uses the specific verb 'Create' with the resource 'location' and adds the qualifier 'physical or business', which helps distinguish it from other create* tools like createCustomer or createTag. It is clear and unambiguous, though it largely restates the title.

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 'for the project' and 'physical or business location' imply when to use this tool, but there is no explicit guidance contrasting it with alternatives such as createCustomer or createSource. The usage context is present but left to inference.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, and non-idempotent, and the description usefully reinforces that behavior by disclosing that it fetches an external public URL and stores it. However, it never says whether an existing project logo is replaced or how the uploaded asset is mutated later, which matters for a write 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?

Two short sentences, with the action front-loaded and zero filler. The only minor waste is repeating the title 'Create Logo' before the substantive sentence.

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

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

For a single-parameter tool with full schema coverage, an output schema, and annotations covering the safety profile, the description is nearly complete. The remaining gap is overwrite/replacement semantics for an existing logo, which the agent would want before calling.

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%: the single 'url' parameter already documents accepted formats (GIF/JPEG/PNG), size limits, pixel bounds, and the 400 error path. The description only restates that the URL must be public, adding nothing beyond the schema, 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 ('Create Logo') and clarifies the mechanism: fetch a public image URL and store it as the project logo. Clear on its own, but gives no differentiation from siblings like createIcon or createReviewShareImage, leaving an agent to guess which image-creation tool applies.

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, no mention of prerequisites such as ownership/branding permissions, and no reference to alternatives (createIcon, getLogo, deleteLogo). The agent must infer all 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.

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

Annotations already indicate a non-read-only, open-world, non-idempotent operation. The description adds a concrete side effect—'creating the customer when needed'—which goes beyond the annotations. It also summarizes optional attributes like source, location, tags, and review date, giving the agent a clearer behavioral model.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded, with the substantive behavior in a single sentence. The only slight issue is that it opens with 'Create Review', which just repeats the tool title, adding minimal extra value.

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

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

The description covers the primary use case and the main side effect, but it implies that email/phone are the identification mechanism while they are optional in the schema. It also leaves nuances like error handling to the schema and does not mention alternative flows or the exact return value, though the output schema exists to fill some of that gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with detailed per-parameter descriptions already present. The tool description only groups parameters into categories (source, location, tags, review date) and does not add new meaning beyond what the schema provides. Baseline 3 is appropriate given the rich schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Create') and resource ('review'), and clearly defines the main behavior: creating a review for a customer identified by email or phone, creating the customer when needed. This distinguishes it from sibling tools like createCustomer or createAsk, and the optional fields are summarized without confusion.

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 clear context for when to use the tool: when a review needs to be created and possibly a customer needs to be created/identified. It does not explicitly name alternatives or state when not to use it, but the scenario is unambiguous and no exclusions are needed.

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, idempotentHint=false, and destructiveHint=false. The description adds meaningful behavioral detail by stating the operation 'persist[s] the image' and returns 'CDN-backed metadata', revealing a persistent side effect and the storage mechanism. It does not contradict the annotations and adds context beyond the 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?

The description is a single sentence that front-loads the core action ('Render a share-card PNG') and then provides the key behavioral details (persist, CDN metadata). There is no filler or redundant material, and the title is not restated beyond the initial line, which is acceptable.

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

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

The tool has a moderate complexity with 3 parameters, all schema-documented, and an output schema exists so return values need not be spelled out. The description covers the essential operation and side effects, though it does not state prerequisites like the review must already exist or the behavior when template_id is invalid. Given the output schema and sibling context, this is adequate.

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?

All three parameters have full descriptions in the schema (100% coverage), so the baseline is 3. The description's mention of 'optional template styling and aspect ratio' maps to template_id and ratio but adds no semantic detail beyond what the schema already provides. id is adequately described in the schema as the review identifier.

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 uses specific verbs and objects: 'Render a share-card PNG', 'persist the image', and 'return CDN-backed metadata'. This clearly distinguishes it from siblings like createReview (which creates review records) and deleteShareTemplate (which deletes templates). The tool name and id parameter description tie it to a specific review, making the purpose 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?

The description establishes clear context: it is used to generate a share-card image for a review, with optional template styling and aspect ratio. It does not explicitly name alternatives or exclusions, but no sibling tool performs a similar image-rendering function, so there is no competing choice to disambiguate. A 4 is appropriate because the context is clear but the description stops short of explicit when-to-use 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 a non-read-only, non-idempotent, non-destructive open-world write, so the bar is lower. The description usefully adds that the slug is derived from the name and that color/sprite only take effect when no custom icon image exists on the source — behavior not visible in the schema. It stops short of noting collision/uniqueness handling or what happens when a duplicate name is submitted.

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 every clause carries information. The only waste is the 'Create Source' heading, which merely restates the tool title.

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 parameters are fully documented in the schema. For a simple three-parameter create tool, the description covers the creation semantics, the derived slug, and the conditional fields without leaving an agent unable to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the parameter descriptions are unusually thorough (length limits, hex formats, Font Awesome class grammar), so the schema carries the load and the baseline is 3. The description adds only the derived-slug relationship and the conditional applicability of color/sprite, not new syntax or format guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Create a review source with a display name.' The resource ('review source') is distinct from the other create* siblings (createIcon, createTag, createReview, createLocation). However, it never explicitly routes the agent away from those siblings or clarifies the relationship to updateSource/listSources.

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 stated when-to-use, when-not-to-use, or named alternative; the agent must infer from the tool name that this is the creation path for sources. The one conditional clause ('color and sprite class apply when no custom icon image is configured') gives partial usage context but is about field applicability 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 readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds nothing beyond that: no statement about name uniqueness, duplicate-creation behavior, permission requirements, or project scoping. It is not contradictory, just empty on behavior.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short lines with no filler and the core action front-loaded. Minor redundancy: the first line merely restates the title, so one of the two sentences carries almost no 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?

An output schema exists so return values need not be explained, and annotations cover safety. However, for a creation tool with six parameters and AI-tagging options, the description omits anything about scope, uniqueness constraints, or how the new tag relates to existing tags, leaving the definition only minimally viable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all six parameters in detail (color hex format, sprite CSS class rules, context enum values). The description's phrase 'for customer or review organization' loosely gestures at the context parameter but adds no syntax or format detail. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create a project tag') plus the organizational scope ('for customer or review organization'), which maps to the context enum. It is distinguishable from createCustomer/createReview and from updateTag/deleteTag, though it never names those siblings.

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, no mention of prerequisites, and no routing to alternatives such as updateTag when the tag already exists. The reader must infer usage entirely from the tool name.

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, idempotentHint=true, and readOnlyHint=false. The description adds valuable context beyond annotations by specifying 'Permanently remove' and narrowing the target to a charge row within this project's customers, clarifying irreversibility and scope.

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 meaningful instruction is compact and front-loaded. The only minor inefficiency is repeating the title 'Delete Charge' as the first line of the description, but the rest is concise and focused.

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 one-parameter destructive action with an output schema and strong annotations, the description provides everything needed to invoke correctly: the object type, the scope, the permanence, and the purpose. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema coverage is 100%, and the sole parameter 'id' is already described as 'Unique numeric identifier for this charge row.' The description itself adds no additional parameter-level meaning, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Permanently remove'), a specific resource ('charge row'), and a scope ('scoped to this project's customers'). This clearly distinguishes it from the many other delete* sibling tools such as deleteCustomer and deleteMessage.

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 provides clear context about when this tool is appropriate: for a 'mistaken charge row' scoped to the project's customers. It does not explicitly name alternatives or state when not to use it, but the intended use case is evident.

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?

The annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is covered. The description adds the 'authenticated project' scope, but it does not disclose additional behavioral traits such as permanence, cascading effects, or authorization requirements beyond what annotations already provide.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short and front-loaded with the core action. However, the first line 'Delete Customer' simply repeats the tool title and does not earn its place, preventing a perfect score.

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 single-parameter destructive operation, the description plus annotations provide sufficient context for an agent to invoke it correctly. The output schema exists, the parameter is fully documented, and the destructive nature is covered by annotations. The only notable gap is the missing guidance about delete versus archive alternatives.

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 the only parameter 'id' is already described as 'Unique numeric identifier for the customer.' The tool description adds no additional meaning about the parameter, so the baseline score of 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: 'Delete a customer from the authenticated project.' This clearly identifies the operation and differentiates it from sibling tools like archiveCustomer, deleteCharge, and deleteReview by naming the exact resource being deleted.

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 is given about when to use this tool versus alternatives. In particular, the sibling archiveCustomer exists, but the description does not explain when to delete versus archive a customer, nor does it mention any prerequisites or contextual conditions.

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, idempotentHint=true and openWorldHint=true, so the bar is lowered. The description still adds real value by disclosing the two non-obvious side effects: hosted-page metadata is synced while the stored image file is left in place. That clarifies what is and isn't destroyed.

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 immediately qualified by the side effects. No redundant restatement beyond the unavoidable title echo.

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

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

An output schema exists so return values need no explanation, and annotations cover the safety profile. The description supplies the scope caveats (metadata sync, file retention) that an agent needs to set expectations, leaving only minor gaps around auth or error behavior.

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?

The tool takes zero parameters, so the baseline is 4. There is nothing parameter-wise for the description to compensate for, and the schema is fully self-describing.

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 (Delete/Remove) and resource (project icon), distinguishing it from siblings like deleteLogo and getIcon. The name plus title plus description line up without ambiguity.

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 the destructive delete framing, but no explicit when-to-use or alternatives are named, even though siblings such as getIcon and createIcon form an obvious cluster. An agent can infer the intent but gets no 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 carry readOnlyHint=false and destructiveHint=true; the description adds the authorization-related behavioral detail that the location must be owned by the authenticated project. It does not contradict annotations and is consistent with the deletion semantics.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded, but the first line 'Delete Location' repeats the tool name/title. The second sentence earns its place by adding the resource and ownership scope.

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 one-parameter deletion tool with an output schema and rich annotations (destructive, idempotent, readOnly=false), the description plus structured metadata fully covers what an agent needs: what is deleted and the ownership precondition. No critical behavior or parameter details are 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%, and the single 'id' parameter is already documented as a unique numeric identifier. The tool description adds no parameter-level meaning, so the schema carries the full burden, matching the baseline for high 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?

Description uses specific verb 'Remove' with explicit resource 'project location' and scoping condition 'owned by the authenticated project'. This clearly differentiates it from getLocation, updateLocation, listLocations, and other delete tools.

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 ownership constraint ('owned by the authenticated project') functions as a precondition for when the tool applies, and the delete action is self-selecting among location siblings. It does not explicitly name alternatives or when-not conditions, but gives enough context to decide.

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds a genuinely useful non-obvious detail — that the stored image file is left in place — which the 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?

Very short and front-loaded, with the operative verb in the first sentence. Minor waste from repeating the title 'Delete Logo' before the actual description, but the file-retention note earns its place.

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

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

An output schema exists, so return values need not be described, and annotations carry the destructive/idempotent contract. Combined with the file-retention caveat, this is sufficient for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4. The description correctly implies the target is the project's own logo with no argument needed, with schema coverage at 100%.

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 the project logo'), which cleanly separates it from getLogo and createLogo in the sibling set. It does not explicitly name or distinguish against an alternative, so it falls 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?

There is no guidance on when to use this versus alternatives, no prerequisites, and no mention of what happens if no logo exists. The sentence about the stored file is a behavioral note, not usage direction.

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 provide readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the description's 'Delete' is consistent. It adds minimal extra behavioral context beyond the annotations, mainly the scheduled/sent scope, which is mostly purpose rather than side effects.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short and the meaningful sentence is front-loaded. However, it repeats the tool title 'Delete Message' as a heading, which is redundant given the title field is already present.

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

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

For a single-parameter delete operation with an output schema and annotations covering the destructive and idempotent behavior, the description provides all necessary context. The scope of what can be deleted is clearly stated, and no return-value explanation is needed because an output schema exists.

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 the single id parameter is already documented as 'Unique numeric identifier for this message.' The description adds no further parameter-level meaning, so the baseline of 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 uses a specific verb ('Delete') and resource ('scheduled or sent outreach message') and adds scope ('for the authenticated project'). This clearly distinguishes it from listing, updating, or canceling tools, even without naming a sibling.

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 clear context by specifying the message states this tool applies to: scheduled or sent outreach messages. It does not explicitly exclude alternatives like cancelCustomerUnsentMessages, so it stops short of full 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?

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is covered. The description adds only the 'no longer be reconciled' rationale and does not contradict the annotations, but it also does not disclose additional behavioral details such as permanence, cascading effects, or permissions.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and the meaningful instruction is front-loaded. The first line 'Delete Review' redundantly repeats the tool name, but the rest is a single purposeful sentence with no wasted words.

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 single-parameter destructive operation, the description is largely complete, especially with annotations covering destructiveness and idempotency and an output schema present. The main gap is the lack of explicit guidance on when deletion is preferred over less destructive review updates, but this is not critical for basic invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single id parameter is documented, though generically as 'Unique numeric identifier for this resource.' The description adds no parameter-specific meaning, so the baseline of 3 applies because the schema carries the semantic weight.

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 ('Remove') and resource ('a review'), so an agent can tell this deletes a review rather than a charge or customer. The phrase 'should no longer be reconciled' adds intent, but it does not explicitly differentiate this from review-related alternatives like updateReviewVisibility or markReviewReplied.

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 implies when to use the tool: when a review should no longer be reconciled. However, it provides no explicit alternatives, no when-not-to-use guidance, and no mention that hiding or flagging might be a less destructive option. The situational cue is present but vague.

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 carry destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description goes beyond them by disclosing the conditional side effect: promoting another default when the deleted template was the default. This is relevant behavioral context that an agent would not infer from annotations alone.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is exceptionally concise: two short sentences, with the core action front-loaded and the optional conditional detail in the second sentence. No filler or redundancy.

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 one-parameter destructive operation with an output schema and rich annotations, the description covers the essential domain-specific behavior (default promotion). It does not specify error cases or behavior when no default exists, but these are not critical for a simple delete operation and are partially covered by annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides a complete description for the single 'id' parameter ('Unique numeric identifier for the share template'). The description adds no parameter-level detail, so with 100% schema coverage the baseline of 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 clear, specific operation: 'Remove a share template' and adds a distinctive conditional detail about promoting another default when the deleted row was default. This precisely identifies the resource and behavior, distinguishing it from other delete tools and from listShareTemplates.

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 the imperative 'Remove a share template' and the tool name, but there is no explicit guidance on when to use this tool versus alternatives, nor any exclusion conditions. The sibling list contains no other share-template deletion tool, so this gap is minor but still present.

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 idempotentHint=true, so the safety profile is covered. The description adds valuable context beyond annotations by specifying this is a soft-delete, implying reversibility or archival rather than permanent removal. It doesn't detail consequences for related resources, but the annotations lower the bar for this dimension.

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 useful content is a single, efficient sentence that states the action and condition. However, the first line 'Delete Source' merely repeats the title and adds no value, so it is not entirely waste-free.

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 one-parameter tool with an output schema and annotations covering destructive/idempotent behavior, the description is nearly complete. It explains what soft-delete means and when to use it. The only minor gap is the absence of details about what happens to related data (e.g., reviews tied to the source), but this is not essential given the tool's simplicity.

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%, with the single 'id' parameter already documented as 'Unique numeric identifier for this review source.' The tool description adds no additional parameter meaning beyond the schema, so the baseline score 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?

The description states a specific verb ('soft-delete') and resource ('review source'), and provides the purpose ('when it is no longer used for ingestion or display'). This clearly distinguishes it from siblings like createSource, updateSource, and listSources without needing to inspect their schemas.

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

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

The description gives a clear condition for use: delete a source when it is no longer used for ingestion or display. It does not explicitly name alternatives or exclusion scenarios, but the condition is specific enough to guide an agent's decision. A small deduction for not mentioning when not to use it (e.g., if the source is still referenced).

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, readOnlyHint=false, and idempotentHint=true. The description adds the key context of 'soft-delete', indicating the tag is not permanently destroyed but hidden or marked as deleted, which is valuable beyond the annotations. It also notes the tag is 'shared across customers and reviews', giving insight into its scope. No contradiction with annotations.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is exceptionally concise: two sentences, zero filler. The key action ('Delete Tag') is front-loaded, followed by a precise clarification of the deletion behavior and scope. Every word 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 single-parameter tool with an output schema present, the description covers the essential behavioral aspects: what is deleted, how (soft-delete), and its shared scope. It does not discuss side effects or return values, but the output schema handles return details, and the annotations cover destructive/idempotent behavior. The information is sufficient 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?

The schema description coverage is 100%, and the 'id' parameter is fully documented as a unique numeric identifier. The description adds no extra semantic detail about the parameter, so it neither enhances nor detracts from the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Delete') and resource ('Tag'), and clarifies it is a soft-delete of a workspace tag shared across customers and reviews. This clearly distinguishes it from createTag, updateTag, and listTags among the siblings. The purpose is unambiguous and precise.

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 provides clear context that this tool soft-deletes a tag, implying it is the appropriate choice for removing a tag from active use. It does not explicitly name alternatives or state when not to use it, but the scope is clear enough that an agent would not confuse it with create/update/list operations. There are no misleading cues.

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, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds genuine context beyond that: the authenticated-project scoping (an auth requirement) and the exact data returned, which is the kind of auth/scope disclosure the rubric credits.

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 lines, front-loaded and free of filler. Minor deduction because the leading line 'Get Branding' merely restates the tool name and title before the informative sentence begins.

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 zero-parameter read with full annotations and an output schema, the description need not explain return values (it does anyway). Nothing an agent requires to invoke this correctly is missing; only the overlap with similarly named get* siblings is left unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, which sets the baseline at 4. The schema has no properties to document, and the description introduces no misleading parameter references.

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 (Get / Branding) and adds real specificity by naming the payload ('primary color and logo height'), which separates it from siblings like getSettings or getMeta. However, it never names or differentiates itself from updateBranding or from the adjacent getLogo/getIcon tools, so the sibling-differentiation bar for a 5 is not met.

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

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

The only usage signal is the scope phrase 'for the authenticated project'. There is no statement of when to prefer this over getSettings, getMeta, getLogo, or getIcon, and no prerequisites or exclusions. An agent must infer selection from the returned-field list 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 already cover readOnly, idempotent, non-destructive behavior, lowering the disclosure burden. The description adds useful context about project scoping and conditional nested location/tags inclusion, which is not present in the annotations. No contradiction exists.

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 substantive sentence is tightly worded and front-loaded, but the description begins by repeating the tool title 'Get Customer' before adding real content. Overall it is concise and easy to parse.

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 one-parameter read operation with an output schema and safety annotations, the description provides everything needed: resource, cardinality, project scope, and optional nested data. No critical information for correct invocation 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?

The input schema fully documents the 'id' parameter as a unique numeric identifier with 100% coverage, so the baseline of 3 applies. The description adds no additional meaning about the parameter beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Retrieve one customer belonging to the authenticated project with nested location and tags where present,' providing a specific verb, resource, cardinality, and scope. This clearly distinguishes it from listCustomers (many customers) and getLocation (location resource).

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

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

The description clearly implies use when a single customer is needed by ID within the authenticated project, especially when nested location and tags are desired. However, it does not explicitly name alternatives or state when not to use this tool.

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, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered. The description adds one genuinely useful behavior beyond that — returning null when no icon is set — but says nothing about permissions or scope.

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 with the core behavior front-loaded. The leading 'Get Icon' line merely restates the title and is mild waste, but the rest earns its place.

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

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

An output schema exists so return shape need not be explained, and annotations carry the safety profile. For a zero-parameter read tool, stating the resource and the null case is nearly complete; only sibling disambiguation 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?

The tool takes zero parameters, so there is nothing for the description to document; baseline is 4. Schema coverage is reported at 100%.

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 ('Return the current project icon') and adds the null edge case. It does not explicitly differentiate from the close siblings getLogo and getBranding, so an agent must infer that 'icon' and 'logo' are distinct resources.

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 and no mention of alternatives such as getLogo or getBranding, despite three closely related retrieval siblings. The agent gets no help deciding which of these to 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 declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds minimal behavioral context beyond the retrieval action itself; the use-case mention is purpose-oriented rather than behavioral.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded, with the core action in the first substantive sentence. The redundant heading 'Get Location' repeats the tool name and adds no value, but the overall structure is efficient and easy to parse.

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 get-by-id tool with a rich output schema and strong annotations, the description is largely sufficient. It does not explain what a 'project location' is or what 'display slug' means, but these are minor gaps given the low complexity and available structured metadata.

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 the only parameter 'id' is already documented as a unique numeric identifier. The description adds no additional parameter-level meaning, so the baseline score of 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 ('Retrieve') and resource ('a single project location'), clearly distinguishing it from listLocations. It also names two concrete use cases, 'display slug or reconciliation use', which helps an agent understand the tool's role.

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 implies usage when a single location is needed, but it does not explicitly contrast with listLocations or other location-related tools. There is no when-not-to-use guidance or mention of alternatives, leaving the agent to infer the boundary.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description usefully adds that it returns null when no logo is set, a behavioral trait beyond the annotations, but it offers nothing further about auth, scoping, or response 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?

Two short sentences, front-loaded, with no wasted text. Minor redundancy in restating the title as a heading, but negligible.

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 zero-parameter read with annotations carrying the safety profile and an output schema covering the return value, the description is nearly complete; only sibling routing is unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters and the schema is empty, so there is nothing further to document; baseline 4 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 (get) and resource (project logo) and notes the null-when-unset case. It is implicitly distinguishable from createLogo/deleteLogo, but it does not explicitly differentiate itself from adjacent read tools like getIcon or getBranding, 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?

There is no when-to-use guidance or mention of alternatives such as getBranding or getIcon for related asset retrieval. The only additional context is an edge-case return value, not selection guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only the scoping detail that the result is the authenticated project's public meta, which is modest extra context rather than new behavioral disclosure.

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 operative sentence is a single, front-loaded clause with no filler. The only waste is the redundant 'Get Meta' heading that merely restates the tool title.

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 zero-parameter read with an existing output schema, the description is essentially sufficient; return values are even described despite the output schema carrying that burden. The one gap is routing guidance among the numerous sibling getters.

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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. Schema coverage is 100% and the empty object schema matches the description's implication of a no-argument call.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Return the public page title and description for the authenticated project'), which is more precise than the bare title 'Get Meta'. It implicitly distinguishes itself from getBranding/getSettings by scoping the return to title and description, though it never names those siblings.

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 call this versus the many other get* siblings (getBranding, getSettings, getCustomer, etc.). The agent can infer it is a project-metadata read, but no trigger conditions, prerequisites, or alternatives 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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered by structured data. The description's only added behavioral context is the "authenticated project" scoping; it says nothing about caching, freshness, or what is excluded from "general" settings.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the substantive scoping detail in the second. Minor waste in that the first line merely restates the tool name and title rather than adding 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?

With zero parameters, rich annotations, and an output schema that documents the return shape, the description carries little burden and covers the essentials. Its one real gap is failing to differentiate this tool from the other no-arg getters in the sibling set.

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?

The tool takes zero parameters, so the schema has nothing to document and the baseline is 4. The description correctly implies no input is required by framing the call as simply returning the project's settings.

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?

"Return general project settings for the authenticated project" gives a verb plus a resource and scopes it to the authenticated project, which is more than the bare name. However, "settings" is broad and the definition does nothing to distinguish it from close siblings like getMeta, getBranding, or updateSettings, leaving the agent to guess at the boundary.

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, no stated prerequisites, and no mention of alternatives. The agent is never told when to reach for getSettings versus getMeta or getBranding, so selection is left entirely to inference.

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

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

Annotations already establish safe read-only, idempotent behavior, so the bar shifts to added context. The description adds concrete behavioral details: endpoints are paginated, at most 30 records per page, and the pagination object should be inspected to decide whether to continue fetching.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with the core purpose, followed by the only essential behavioral guidance. The redundant 'List Charges' opener is minor, and every substantive sentence earns its place.

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

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

Given full parameter documentation, a rich output schema, and annotations covering safety, the description is nearly complete. The only small gap is the lack of explicit differentiation from the closely related listCustomerCharges sibling, though the 'authenticated project' scope largely covers this.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents page, limit, date_to, and date_from. The description only restates page/limit semantics and the 30-record cap, adding no meaningful meaning beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('List') and resource ('revenue charge rows for the authenticated project'), with a clear scope qualifier ('authenticated project') that differentiates it from customer-scoped siblings like listCustomerCharges. The optional calendar bounds are also named, making the operation 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?

The description clearly conveys when this tool applies: listing project-level revenue charges, optionally bounded by charged-at dates. It gives explicit pagination usage context but does not mention alternatives or exclusions, such as when to prefer listCustomerCharges.

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, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral detail about pagination (page/limit parameters and the pagination object in the response) beyond what annotations provide, so the agent knows how to handle large result sets.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded with the core purpose, followed by pagination instructions. It repeats the tool name in the first line, but that is minor. The structure is logical and easy to scan, with no unnecessary fluff.

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

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

Given the tool's simplicity (3 params, one required) and the presence of an output schema, the description covers what an agent needs: the resource scope, pagination handling, and how to detect more pages. It's complete for a read-only list endpoint.

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% with clear descriptions for id, page, and limit. The description adds extra meaning by explaining the pagination object and how to check for more pages, which goes beyond the schema's basic parameter definitions.

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 action: listing revenue-charge history for a single customer, and distinguishes it from the sibling listCharges (which likely covers all customers). The phrase 'for one customer' makes the scope explicit, so an agent can immediately tell it apart from other list tools.

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

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

The description clearly indicates this is for a single customer's charge history and explains pagination mechanics. It doesn't explicitly name alternatives or state when not to use it, but the 'for one customer' scope provides clear context that implies listCharges would be used for all customers.

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?

The description adds meaningful behavioral context beyond the annotations: it discloses that list endpoints are paginated, caps results at 30 per page, and tells the caller to inspect current_page, last_page, and total to determine whether more pages exist. This is useful runtime behavior that annotations alone 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?

The description is compact and front-loaded with the main purpose before pagination details. The opening line repeats the tool title, which is mildly redundant, but every other sentence earns its place by giving operationally useful pagination instructions.

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 three-parameter read-only list tool with an output schema and strong annotations, the description is complete. It tells the agent what the tool does, how to paginate, and how to recognize whether more pages exist, so no critical information needed 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 coverage is 100%, so the schema already documents id, page, and limit. The description reinforces the pagination purpose of page and limit and notes the 30-record cap, but it does not add meaning beyond what the schema properties already state.

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: 'Retrieve message history for one customer.' The explicit 'for one customer' scope distinguishes it from siblings like listMessages, which presumably returns all messages, without needing to open any schema.

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

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

The description provides clear pagination guidance: use page and limit, at most 30 records per page, and check the pagination object to decide whether to keep fetching. However, it does not explicitly state when to prefer this over listMessages or other listing tools, relying only on the implied per-customer scope.

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 read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral detail about pagination: page/limit usage, the 30-record cap, and the pagination object fields to inspect for continuation. This goes beyond what the annotations provide.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded: the core purpose appears in the first sentence, with pagination details following. The initial repeated title line is slightly redundant, but every other sentence earns its place and the overall length is well controlled.

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 paginated list endpoint with full schema coverage and an output schema, the description covers what an agent needs: what it retrieves, the customer scope, pagination mechanics, and how to determine whether more pages exist. No critical behavioral gap remains.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents id, page, and limit. The description reinforces pagination semantics and the 30-record limit, but it does not add substantial new meaning beyond what the schema already states. This is the appropriate baseline for high 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 states a specific verb and scope: 'Retrieve review history for one customer in the project.' This clearly distinguishes it from broader review endpoints like listReviews by anchoring it to a single customer. The resource and action are 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?

The description clearly conveys that this is for one customer's review history, which gives the agent context for when to choose it over broader list tools. It does not explicitly name alternatives or exclusions, but the customer-scoped wording provides sufficient guidance for a list endpoint with obvious 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 already establish readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely new behavior: the 30-records-per-page cap, the response pagination fields (current_page, last_page, total) for deciding whether to fetch more, and phone normalization to E.164 with a raw-column fallback for unparseable values.

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, then the routing alternative, then the pagination contract, with no filler. The leading "List Customers" line duplicates the title and is the only wasted element.

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 rich annotations and an output schema present, the description need not explain return values, and it still covers the pagination mechanics and the create/match escape hatch. What's missing is only comparison to sibling list/get tools over the same resource.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description's parameter-level additions (phone E.164 normalization, the 30-record page limit, calendar bounds on a chosen datetime column) largely restate what the schema already documents for phone, limit, date_key, date_from and date_to, adding little beyond it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Retrieve project customers") and enumerates the filter/sort dimensions available, which distinguishes it from single-record siblings like getCustomer. It does not name a list-vs-get alternative explicitly, so it stops short of full sibling differentiation.

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 routing rule for a related case: "To create or match by contact without an id, use POST /customers (email first, then phone)," and prescribes the pagination workflow (use page/limit, inspect the pagination object). It doesn't say when to prefer listCustomers over getCustomer or listCustomerCharges, so the exclusion set is incomplete.

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, idempotent, and non-destructive traits. The description adds the 'active' filter and the intended use of results, which is useful context beyond the annotations. It does not mention potential open-world limitations or whether pagination applies, but the annotations ease the burden.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded with the key behavioral fact. The first line repeats the title, which is slightly redundant, but the second sentence adds meaningful context without waste.

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 parameters, a clear statement of scope ('every active location'), annotations covering safety/idempotence, and an output schema present, the description is complete for an agent to select and invoke this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so the baseline is 4. The description correctly focuses on behavior and result scope rather than parameter details, which are unnecessary 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?

The description states a specific verb ('Retrieve') and resource ('every active location'), and clearly differentiates from siblings like getLocation by indicating this is a list operation over all active locations. The purpose is immediately understandable.

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 clear intended contexts: 'for slug references or reconciliation with upstream systems.' It does not explicitly name exclusions or alternatives, but for a zero-parameter list-all tool the usage context is sufficiently clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds useful behavioral detail beyond that: list endpoints are paginated, there is a 30-record-per-page cap, and the response includes a pagination object with current_page, last_page, and total to guide further fetching. No contradiction with annotations.

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 body is compact and front-loaded: purpose in the first paragraph, pagination usage in the second. The only redundancy is the opening 'List Messages' line, which repeats the tool title, so it isn't a perfect 5.

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

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

Given 10 optional parameters, rich schema, output schema, and annotations, the description covers the core call and pagination behavior. However, it leaves the relationship to listCustomerMessages unspecified and uses the vague term 'recent' without defining the default time range, so an agent could still be uncertain about tool selection and scope.

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?

Input schema coverage is 100%, with each parameter described in the schema itself (e.g., date_from/date_to format, date_key enum, limit max 30). The description mentions page/limit and calendar bounds but does not add meaning beyond the schema, so it sits at the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action and resource: retrieve recent project outreach messages for reporting or auditing, and mentions optional calendar bounds on a datetime column. It distinguishes the tool from unrelated list endpoints (e.g., listCharges, listCustomers) but does not explicitly contrast with the sibling listCustomerMessages, so it falls 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?

It provides clear usage context for reporting/auditing and explains pagination via page/limit and inspecting the pagination object. However, it gives no when-to-use vs alternatives, particularly failing to say when to choose listMessages over the sibling listCustomerMessages, leaving the selection criterion implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond those annotations by disclosing pagination mechanics (max 30 records per page) and how to detect remaining pages via the pagination object. It does not contradict any annotation.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two tight paragraphs with no filler. The purpose is front-loaded in the first sentence, and the pagination detail is placed in a separate paragraph that earns its space. Slightly more structure (e.g., naming the sibling alternative) could push it higher, but it is efficient as written.

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 16-parameter tool with an output schema and 100% schema coverage, the description covers the key behavioral aspects an agent needs: the filterable dimensions, sorting options, date-key selection, and pagination flow. The output schema handles return values, so nothing essential for correct invocation is missing, though sibling differentiation would improve it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description does add a light summary of the filter dimensions (facet, source, location, score, tag) and references page/limit and date_key, but it largely restates what the schema already documents in detail. It adds marginal value without compensating for any 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 names a specific verb and resource ('Retrieve project reviews') and enumerates its capabilities: facet/source/location/score/tag filters, sorting by rating or timestamps, and calendar bounds on a chosen datetime column. This clearly distinguishes a general review-listing operation from create/update/delete siblings, though it does not explicitly differentiate it from the closely related listCustomerReviews sibling, 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 pagination paragraph gives practical 'how to use' guidance (page/limit, 30-record cap, check pagination object), and the filter list implies a general-purpose listing role. However, there is no explicit when-to-use versus when-not-to guidance, especially against the near-identical listCustomerReviews sibling, so usage is only implied 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=true and destructiveHint=false, so the safety profile is covered. The description adds value by stating that all templates are returned and that default flag and layout settings are included, but it does not mention ordering, pagination, or any other runtime behavior. This is adequate for a zero-parameter list 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?

The description is brief and front-loaded with the action and resource. The first sentence repeats the tool title, which is slightly redundant, but the second sentence adds meaningful detail about the returned data. Overall, there is no wasted 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?

For a zero-parameter, read-only listing tool with an output schema and comprehensive annotations, the description is fully adequate. It tells the agent exactly what will be returned and nothing else is needed to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, and schema description coverage is 100% per the context signals. The description correctly focuses on the output scope rather than parameter details, since none exist. Baseline 4 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 uses a specific verb ('List'/'Return') and a specific resource ('saved share template'), and clarifies the scope as 'every' template including default flag and layout settings. This clearly separates it from sibling tools that operate on other resources or perform deletion.

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 makes the use case clear: retrieve all saved share templates, including their default flag and layout settings. There are no exclusion conditions or alternatives to compare against; it is a simple read-only listing tool, so the lack of explicit 'when not to use' guidance is acceptable.

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, idempotentHint, and destructiveHint, so the description only needs to add context. It adds that the tool returns 'review source metadata' scoped to 'project reviews,' which is mildly informative but does not disclose deeper behaviors beyond what annotations already cover.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded with the key action. The only minor inefficiency is that the first line repeats the tool name/title ('List Sources'), but the rest is direct and free of unnecessary detail.

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 zero-parameter, read-only list tool with an output schema and strong annotations, the description is largely complete. It states the resource and scope, though it does not explicitly mention whether the list is unfiltered or how many sources it returns, which could be slightly more explicit.

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?

The tool has zero parameters and schema description coverage is 100%, so there are no parameter semantics required. The description correctly avoids inventing parameters and just states what the listing returns.

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 uses a specific verb ('Retrieve') with a clear resource ('review source metadata'), and the scope is narrowed to what is 'available for project reviews.' This clearly differentiates it from sibling source tools like createSource, updateSource, and deleteSource.

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 implies this tool is for read-only listing of review sources, and the sibling names make the distinction obvious. However, it does not explicitly state when to prefer this tool over alternatives or provide any 'do not use when' guidance, leaving usage partially implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructiveness, so the description does not need to restate safety. It adds useful context about tags organizing customers and reviews, but discloses no extra behavioral traits such as pagination, ordering, or filtering nuances beyond the 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?

The substantive sentence is short and front-loaded. The opening 'List Tags' line is redundant with the title and tool name, but the overall length is appropriate and the core purpose is immediately visible.

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 list operation with one optional parameter, a clear purpose, an output schema, and annotations covering safety and idempotency, the combined description and schema are complete enough for an agent to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the optional context parameter is fully documented in the schema. The description's mention of customers and reviews loosely aligns with the parameter's enum values, but it does not add substantial meaning beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb and resource: 'Retrieve project tags used to organize customers and reviews.' This distinguishes listTags from customer/review listing tools, though it does not explicitly contrast it with sibling tag operations like createTag or updateTag.

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 intended use is implied: call this when you need the set of tags used for customers and reviews. However, there is no explicit guidance about when to choose this over alternatives or any exclusions, leaving the routing decision mostly to inference.

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

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

Annotations already declare the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the bar is lower. The description adds that results include embed code and allowed domains, which is useful orientation, but with an output schema present this largely restates return contents rather than adding new behavioral traits like ordering, pagination, or auth needs.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, with the purpose front-loaded and no redundant or filler text. Every sentence earns its place.

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

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

With no parameters, full annotation coverage, and an output schema that presumably details the widget fields, the description supplies enough orientation to invoke the tool correctly. Only minor gaps (ordering/pagination expectations) remain.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (List) and resource (Widgets), and clarifies that widgets are 'embeddable review widgets' carrying an embed code and allowed domains. No sibling tool shares the widget resource, so there is little ambiguity to resolve against listReviews, listTags, etc.

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, what preconditions apply (e.g., account/brand context), or how it relates to alternatives. The listing purpose is inferable, but no explicit guidance is offered.

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=true and idempotentHint=true, so the safety profile is carried by structured data. The description adds the important scope limit that stored reply text is untouched, clarifying what the 'destructive' flag actually applies to. It does not explain the idempotent or open-world implications, so it is not exhaustive.

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 body is a single dense sentence with the core behavior front-loaded. The leading 'Mark Review Replied' heading merely repeats the title and consumes space without adding information, which is the only real waste.

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 a full output schema and rich annotations, the description only needs to convey the operation's intent and scope, which it does. Nothing critical is missing for an agent to call it correctly, though naming the counterpart tool for in-platform replies would make it fully self-sufficient.

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 parameters are already documented, including the true/false semantics of 'replied'. The description's 'set or clear replied_at' restates that mapping rather than adding syntax or edge-case detail. Baseline 3 is correct when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific operation (set or clear replied_at) on a specific resource (review reply state) and adds the key qualifier 'without changing stored reply text', which separates it from the sibling updateReviewIntegrationReply. It stops short of naming that sibling explicitly, so it is clear but not fully disambiguating.

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 states the trigger condition plainly: use this 'when a reply was handled outside the platform'. That is a real when-to-use cue rather than an implied one. It does not name the alternative tool to use when the reply was made through the platform, so the routing guidance is incomplete but usable.

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 indicate a non-read-only, idempotent, non-destructive operation. The description adds the specific behavioral effect: clearing the opt-out flag rather than performing a broader customer update or deletion. This is useful context beyond the structured annotations.

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 actual guidance is a single, front-loaded sentence that efficiently states the action and consequence. The repeated title line 'Resubscribe Customer' is redundant with the tool name and adds no value, slightly reducing conciseness.

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

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

For a simple, single-parameter, idempotent operation with an output schema and comprehensive annotations, the description covers everything an agent needs to know: what state is changed and what the effect is. No critical context 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?

There is only one parameter, and the schema already documents it fully as the unique numeric customer identifier with 100% coverage. The description does not add additional parameter-level meaning, so the baseline score of 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 uses a specific verb ('Clear') and names the exact resource and state being affected ('message opt-out state'), plus the intended outcome ('outreach can resume'). This clearly distinguishes it from sibling tools like unsubscribeCustomer and archiveCustomer.

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 implies when to use the tool: when a customer's message opt-out state should be cleared so outreach can resume. However, it does not explicitly state when not to use it or mention related alternatives such as unsubscribeCustomer, leaving the selection guidance to inference.

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

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

Annotations cover the safety profile (readOnlyHint=false, non-idempotent, but non-destructive), and the description adds that delivery goes through 'configured' channels, hinting at a setup prerequisite. It does not disclose that real messages are dispatched, whether sending is rate-limited, or that reminders_count triggers follow-up sends — meaningful gaps for an outward-facing action.

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 substantive sentence is tight and front-loaded, but it is preceded by the disconnected 'Create Ask' fragment, which reads as leftover artifact text and dilutes the opening.

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 the 100%-covered schema carries parameter detail. Combined with annotations declaring the write/open-world profile, the description is sufficient for an agent to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents email, phone, asked_at, channels, and reminders_count in detail. The description's channel mention reinforces the required enum parameter but adds no syntax or format detail beyond the schema; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The second sentence gives a specific verb (schedule) and resource (review request outreach) with the delivery mechanism (email or SMS). It distinguishes the tool from createReview, which records a review, though the leading 'Create Ask' fragment is stray noise that adds nothing.

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 createReview or the other review-related siblings, and no mention of prerequisites such as channels needing to be configured beforehand. Usage is only implied by the word 'outreach'.

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 readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond the annotations by explaining that unarchiving affects how asks and integrations treat the customer. It doesn't address edge cases like already-active customers, but that is minor given the idempotency hint.

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 substantive description is one concise, front-loaded sentence with a clear action and outcome. The repeated heading 'Unarchive Customer' is slightly redundant with the tool title, but the overall definition remains compact and scannable.

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 one-parameter mutation with a full input schema, an output schema, and annotations covering idempotency and safety, the description provides sufficient context. It tells the agent what to do and what downstream effect to expect. The only minor gap is behavior when the customer is already active, which is mitigated by idempotentHint=true.

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%; the single 'id' parameter is already described as a unique numeric identifier. The description adds no further parameter-level detail, but none is needed because the schema fully documents the only 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 states a specific action verb ('Restore'), a specific resource ('an archived customer'), and a concrete outcome ('asks and integrations treat them as active again'). This clearly differentiates it from the sibling archiveCustomer and any other 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 description implies the usage context clearly: use when a customer is archived and should become active again. It does not explicitly name alternatives or exclusions, but the inverse sibling archiveCustomer is evident from the wording, giving the agent enough context.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds useful specifics beyond that: it discloses which state changes occur (future outreach disabled, unsent messages cancelled), which is exactly the kind of side-effect detail the hints 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 functional sentence is short, front-loaded, and free of filler. The only waste is restating the tool title as a standalone heading above the actual description, which adds no 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?

With an output schema present, return values need no explanation, and the annotations carry the safety profile. The description supplies the remaining essential context: what the customer state change actually is. Nothing critical for correct invocation 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?

There is a single required parameter whose schema description coverage is 100% ('Unique numeric identifier for the customer'), so the schema fully documents it. The description adds no format, lookup, or resolution guidance beyond the word 'customer', making the baseline 3 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 ('Unsubscribe a customer') and goes further by naming the effect: halting future outreach and cancelling queued messages. It is clear what the tool does, but it does not distinguish itself from close siblings like cancelCustomerUnsentMessages or resubscribeCustomer, which overlap with its described behavior.

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 rather than stated: the described effect (stop future outreach, cancel unsent messages) tells an agent what situation calls for it. However, no alternatives or exclusions are named despite the presence of directly relevant siblings such as cancelCustomerUnsentMessages (partial overlap) and resubscribeCustomer (the inverse operation), and no preconditions are given.

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 full safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true). The description adds one genuinely useful behavioral fact — omitted fields are left unchanged — but says nothing about permissions, scope of persistence, or whether the update applies account-wide.

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 that are front-loaded with the action and fields, then the partial-update rule. Only waste is the leading repetition of the title 'Update Branding', which adds nothing.

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

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

An output schema exists, so return values need not be explained, and annotations cover idempotency and safety. With both parameters fully documented in the schema and the partial-update rule stated, an agent has enough to call it correctly; only auth/permission context 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%: logo_height carries its pixel range (20-200) and color_primary carries the hex format with a leading '#'. The description merely names the two fields, so it adds no meaning beyond the schema; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource ('Update the primary color or logo height'), which is exactly what the tool does. It doesn't explicitly name the sibling getBranding as the read counterpart, but the branding scope is unambiguous against the other update* tools, which target different resources.

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?

'Omit fields you do not want to change' gives practical invocation guidance for a partial update, which is useful. However, there is no explicit when/when-not or reference to alternatives such as getBranding for reading current values, so usage guidance is only implied.

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

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

Goes well beyond the annotations (destructiveHint, idempotentHint) by disclosing partial-update semantics, E.164 phone normalization, the 409 conflict condition and its exception when the value matches the customer's own current data, and the 404 for an unknown location_slug. These are exactly the behavioral traits an agent needs before mutating a record.

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

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core operation and the partial-update rule, then conflict behavior, then the alternative. Efficient overall, though the leading 'Update Customer' line merely repeats the title field and could be dropped.

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 the description still covers the failure modes (409, 404) an agent must handle. For an 11-parameter mutation tool this is complete enough to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3; the description adds real meaning by specifying that only fields present in the body are changed and by enumerating the mutable set (email, phone, name, location_slug, address fields). It does not add format or constraint detail beyond normalization, which the schema already covers for phone.

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 ('Partially update a customer by id') and immediately clarifies the PATCH-style semantics that only body-present fields change. It also names the sibling operation it is not (POST /customers for create/match), so an agent can distinguish it without opening another schema.

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

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

Gives a clear routing rule: to create or match by contact fields without an id, use POST /customers (email first, then phone). That is explicit context for choosing between the two. It stops short of addressing the neighboring update siblings (updateCustomerNotes, updateCustomerPhoto, updateCustomerTags), so it is clear but not fully exhaustive.

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, idempotentHint=true, and openWorldHint=true, so the bar is lowered. The description reinforces the destructive nature by saying notes are 'replaced' rather than appended, but adds nothing about the 5000-character constraint, permission needs, or what happens to prior note content.

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?

Very short and front-loaded, with the operative semantics ('replace') in the first clause. It loses a point only because the title is restated verbatim as the first line, which is redundant with the tool title.

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

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

An output schema exists, so return values need no explanation, and annotations cover the safety profile. What is missing is routing guidance against updateCustomer and any note about the destructive overwrite implications — enough to be usable but not complete for a mutation tool with many siblings.

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 (id, notes) carry their own descriptions including the 5000-character limit, so the schema does the heavy lifting. The description adds no syntax, format, or null-handling detail beyond what the schema already provides — 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 ('Update Customer Notes') and clarifies the semantics with 'Replace the internal notes stored on a customer,' which distinguishes it from generic customer-field updates like updateCustomer. However it never names or contrasts with that sibling, so differentiation is only implied.

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 tool versus updateCustomer, or under what circumstances notes should be replaced at all. The only usable context is the verb 'replace,' which the agent has to infer as the selection condition.

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