More Good Reviews

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds meaningful context about the cancel-unsent-messages behavior, which is not captured in the annotations. However, it does not explain whether archiving is reversible or how idempotency manifests.

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 action, but it redundantly repeats the tool name 'Archive Customer' as the first sentence. The second sentence adds the side effect. Overall it is concise with minimal 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 only one parameter and an output schema present, the description covers the main effect and side effect. It does not specify what 'archive' means for customer status or whether the cancel operation applies to all unsent messages, but these are minor gaps 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 coverage is 100%, and the single parameter 'id' is clearly described as a unique numeric identifier. The description adds no additional parameter semantics beyond what the schema provides, so 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 clearly states the primary action ('Archive a customer') and adds a specific side effect ('cancel any unsent outreach messages'). This distinguishes it from related siblings like deleteCustomer (destructive) and unarchiveCustomer (reverse operation), 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 implies usage via the side effect (archiving when you want to cancel unsent outreach) but does not explicitly state when to use this tool over alternatives like deleteCustomer or unarchiveCustomer. There is no mention of conditions or exclusions.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by clarifying that the operation does not affect subscription state or archive the customer, which are non-obvious side effects. This goes beyond the annotation hints.

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 core action. The first sentence repeats the title, but the second sentence adds the key scoping information efficiently. No wasted words or excessive 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 single-parameter tool with an output schema and safety annotations (idempotent, non-destructive), the description covers what the tool does and what it doesn't do. There are no prerequisites or complex behaviors that need further explanation. The output schema handles return values.

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 provides 100% coverage of the single 'id' parameter with a clear description ('Unique numeric identifier for the customer'). The description does not add additional parameter syntax or format details, 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 clearly states the verb 'Cancel' and the resource 'scheduled outreach for this customer', and explicitly distinguishes from archiving and subscription state changes. This differentiates it from sibling tools like archiveCustomer and unsubscribeCustomer without needing to open 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?

It provides clear context by specifying that it does not archive or change subscription state, helping an agent decide when this tool is appropriate. However, it does not explicitly name alternative tools or conditions for using them, so it stops short of full 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, and the description adds that this is scheduled outreach through configured channels. It does not explain delivery timing, failure behavior, or downstream effects, but the 'schedule review request outreach' phrasing provides useful behavior context beyond 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 informative sentence is concise and front-loaded, but the description begins with a redundant 'Create Ask' line that duplicates the tool name/title. It is short, but not every sentence earns its place.

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

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

With a rich input schema and an output schema, the description is adequate for basic invocation of a schedule-outreach action. However, it lacks explicit usage guidance, prerequisites for configured channels, and behavioral details such as whether messages are sent immediately or queued.

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

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

Schema description coverage is 100%, so the schema already documents all parameters in detail. The description only mentions channels, adding little semantic value beyond what the schema provides for email, phone, asked_at, or reminders_count.

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 action and resource: it schedules review request outreach and names the delivery channels (email/SMS). It does not explicitly distinguish createAsk from siblings like createReview or cancelCustomerUnsentMessages, but 'review request outreach' narrows the meaning enough to avoid major 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?

No when-to-use guidance, exclusions, or alternative tool references are provided. The only implied usage is scheduling review outreach, which is not enough for an agent to confidently choose this over sibling tools such as createReview or createCustomer.

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 indicate this is not read-only, not idempotent, and not destructive, which sets expectations. However, the description does not disclose that creating a customer may have side effects like triggering webhooks or that it returns 404 for invalid location_slug, which is a behavioral detail in the schema. Some credit for the photo_url behavior being in schema, but description doesn't add. No contradiction.

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 brief and front-loaded, consisting of just two sentences. It is concise and doesn't waste words. It could be slightly more structured but is effective for its length.

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 15 parameters and a complex schema (signed_up_at with multiple types) plus an output schema, the description does not provide enough context on return values or error handling. The description is minimal, but the schema covers parameters well. However, for a complex creation tool, more behavioral context is needed, such as what the response contains or how conflicts are handled.

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 description adds little beyond what’s in the schema. It mentions 'contact, location, and tag details' but doesn't explain the relationship or the special behavior of signed_up_at or photo_url beyond 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 it creates a customer record with contact, location, and tag details, which is clear. However, it doesn't distinguish from many sibling tools like createLocation or updateCustomerNotes, though the action of creating a customer is fairly evident. The purpose is clear but generic.

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

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

There is no guidance on when to use this tool vs alternatives. It doesn't mention prerequisites (e.g., location must exist), or the fact that only first_name is required, or that signed_up_at defaults to server time. The description does not help the agent decide when to use this over other creation tools.

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

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

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 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 indicate this is a write operation (readOnlyHint false). The description adds that the slug is auto-generated from the name and that color/sprite apply only when no custom icon image is set. This provides useful behavioral context beyond the annotations, so a 4.

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

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

The description is concise (three short sentences) and front-loads the core action. However, it begins with 'Create Source' which repeats the title, slightly reducing efficiency. Still, it's well-structured and not verbose, so a 4.

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 simple create operation, an output schema exists, and the schema provides full parameter details, the description covers the key behavioral aspects (slug generation, conditional styling). It doesn't mention error handling or idempotency, but those are not essential for a basic create. A 4 is appropriate.

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 covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds that the slug is derived from the name and clarifies the conditional application of color and sprite, which enriches parameter understanding. Thus a 4.

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 'Create a review source' with a specific verb and resource, and notes that the slug is generated from the name. It clearly indicates a creation operation but does not explicitly differentiate from sibling tools like updateSource. The verb 'create' is unambiguous given the sibling list, so it earns a 4.

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 no explicit guidance on when to use this tool versus alternatives. It implies creation via the verb, but doesn't mention that updateSource should be used for modifying existing sources, or any exclusions. This is implied usage, so a 3.

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 disclose readOnlyHint=false, so the description does not contradict anything, but it adds no behavioral context: no uniqueness requirements for the tag name, no duplicate-handling behavior, and no side effects despite openWorldHint=true. With a write operation, an agent is left without information about what creation implies.

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

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

The body sentence is efficient and front-loaded, but it is prefixed by a 'Create Tag' line that merely repeats the tool name and title. Compact overall, but the redundant title line earns a deduction.

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

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

An output schema exists, so return-value documentation is not the description's job, but for a 6-parameter create tool the description omits when to choose it over updateTag/deleteTag, whether names must be unique, and what consequences creation has. It is a minimal purpose statement that is adequate only for the simplest cases.

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 all six parameters, setting the baseline at 3. The description's phrase 'for customer or review organization' echoes the context parameter's enum but adds essentially nothing beyond what the schema already states.

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?

Names a specific action ('Create') and resource ('project tag') and narrows the scope to customer or review organization, which aligns with the context parameter's enum. It is distinguishable from the sibling updateTag/deleteTag/listTags by its verb, though it never explicitly differentiates itself from them.

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

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

Provides no when-to-use guidance, no exclusions, and no mention of alternatives such as updateTag for modifying an existing tag. The only usage signal is the verb 'create', which is implicit rather than explicit instruction.

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 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 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 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, 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 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 carry readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds genuine value by disclosing pagination behavior: at most 30 records per page, use of page/limit params, and how to read the pagination object (current_page, last_page, total) to decide whether to continue. This is behavioral context beyond 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 opening 'List Customers' line duplicates the tool title and adds no information, a minor waste. The substantive paragraph is well-structured and front-loads the purpose before the pagination mechanics, but the redundant header keeps this from being fully tight.

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

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

Given an output schema exists (so return values need no explanation), a 11-parameter read-only list tool, and 100% schema coverage, the description covers the essential operational details: pagination limits, the pagination object, and the filter surface. It is reasonably complete for an agent to invoke correctly, with no critical gaps.

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 of 3 applies. The description's mention of 'search, tag, sort, facet filters, and calendar bounds' maps loosely to q, tag_slug, sort_key/sort_dir, filter, and date_from/date_to/date_key, but adds little beyond what each parameter's schema description already states. It does not compensate for anything missing since nothing is missing.

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 paragraph states a specific action and resource ('Retrieve project customers') plus the full capability set (search, tag, sort, facet filters, calendar bounds). This clearly distinguishes it from the other list tools by naming the customer entity and its filter options, though it does not explicitly name a sibling to differentiate against.

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 ('Retrieve project customers') but no explicit when-to-use vs alternatives is given. The description does not contrast with getCustomer (singular) or the listCustomerCharges/listCustomerMessages/listCustomerReviews siblings, nor state any exclusion conditions. The pagination guidance is operational, not usage-selection.

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

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

Annotations already cover 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 indicate non-read-only, idempotent, non-destructive. The description adds that it specifically modifies replied_at and clarifies it does not alter the stored reply text, which is valuable context beyond annotations. No contradiction.

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 concise sentences that front-load the purpose and then add a clarifying constraint. There's no wasted text.

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 two-parameter tool with a clear schema and output schema, the description covers the essential behavioral information. It doesn't mention error cases or edge conditions, but given the simplicity, nothing critical is missing.

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

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

The input schema fully describes both parameters (id and replied) with their semantics. The description doesn't add significant parameter-level detail beyond what the schema provides, so it relies on the schema's 100% 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 clearly states the action: set or clear replied_at. It also adds a key qualifier ('without changing stored reply text') that distinguishes it from other review update tools, 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?

It specifies the context: 'when a reply was handled outside the platform,' giving a clear condition for use. However, it doesn't explicitly name alternative tools or state when not to use it, so it's slightly less explicit than ideal.

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 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 indicate a non-read-only, idempotent, non-destructive mutation. The description adds useful context about the observable effects: stopping future outreach and canceling unsent messages. However, it does not clarify edge cases such as whether canceled messages remain visible or whether the customer can be resubscribed later.

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, but the trailing 'Unsubscribe Customer' wording in the description duplicates the title and adds no value. Still, the core content 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 tool with one integer parameter, full schema coverage, an output schema, and informative annotations, the description covers the essential behavior. It is incomplete only in that it does not disambiguate from the closely related cancelCustomerUnsentMessages sibling.

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 the unique numeric identifier for the customer. The description adds no additional parameter-level meaning, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource: 'Unsubscribe a customer from future outreach and cancel unsent messages.' This clearly states what the tool does, though it overlaps with the sibling cancelCustomerUnsentMessages because it also mentions canceling unsent messages.

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 provided about when to use this tool versus alternatives such as cancelCustomerUnsentMessages or resubscribeCustomer. The description does not state when not to use it or name any fallback options.

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 tool is not read-only, not destructive, and idempotent. The description adds the important behavior that the notes are 'replaced' (fully overwritten), which is a semantic detail beyond the annotations. However, it does not disclose any potential side effects, such as whether null clears notes or if existing notes are truncated, but this is a minor gap.

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

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

The description is extremely concise: 'Update Customer Notes' followed by 'Replace the internal notes stored on a customer.' It is front-loaded with the key action and has zero filler. 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 tool with only two parameters, 100% schema coverage, and an output schema, the description is sufficient. It explains the core action, and the schema handles parameter details. The only omission is potential edge-case behavior (e.g., passing null to clear notes), but that is implied by 'Replace'. Overall, adequate 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 covers both parameters with descriptions (id and notes), so baseline is 3. The description's use of 'Replace' adds nuance that the notes parameter is overwritten entirely, providing slight extra meaning beyond the schema. However, it does not explicitly describe parameter semantics beyond that.

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 verb ('Replace') and resource ('internal notes stored on a customer'), which precisely identifies what the tool does. It differentiates from sibling tools like updateCustomerTags or updateCustomerPhoto by focusing specifically on notes.

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

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

No explicit guidance on when to use this tool versus alternatives, but the name and description make it obvious that it is used when updating customer notes. There is no mention of when not to use it or alternative workflows, but the simplicity of the operation makes the usage implicit.

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 discloses important behavioral details (downloads URL, stores it, null removes, 400 on invalid URL), but it directly contradicts the annotation destructiveHint=false because passing null removes the existing photo, which is a destructive operation. This is an annotation contradiction.

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 action, but it repeats the tool title 'Update Customer Photo' at the start. The additional sentences on return values and error handling earn their place.

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

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

For a two-parameter tool with a rich schema and output schema, the description covers setting, clearing, return payloads, and error conditions. Nothing essential is missing 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?

Schema description coverage is 100%, so the baseline is 3. The description largely restates the url parameter semantics already present in the schema, adding only the return behavior on set vs. clear, which is not parameter-specific.

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 action ('Download a public image URL and store it as the customer photo') and explicitly covers the null removal case, making the tool's purpose unambiguous and distinct from sibling update tools like updateCustomerNotes or updateCustomerTags.

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 states when to use the tool: to set a customer photo from a public URL or clear it with null. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select it over sibling tools.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds the key behavioral fact that existing tag assignments are replaced, which is useful context beyond the annotations, but it does not disclose potential open-world effects despite openWorldHint=true.

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 content is in the second sentence. The first line repeats the title, which is minor redundancy, but overall the description is appropriately sized and front-loaded with the core behavior.

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 two-parameter tool with full schema coverage, an output schema, and safety annotations, the description is largely complete. It could be improved by noting when to choose this tool over updateTag or updateReviewTags, but nothing essential for invoking it correctly is missing.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters. The description's mention of 'slug list' adds little beyond the schema, and the empty-array-clears-tags behavior is already in 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 ('Replace') and resource ('tag assignments for a customer'), and clarifies the mechanism ('using the provided slug list'). This clearly distinguishes it from sibling tools like updateTag or updateReviewTags, which operate on 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?

The description gives no guidance on when to use this tool versus alternatives such as updateTag, updateReviewTags, or createTag. It implies usage through its purpose statement but provides no exclusions, prerequisites, or alternative 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 communicate that this is a non-read-only, idempotent, non-destructive update. The description adds that the update concerns display and address details, but it omits the internal fields (name, slug, store_code) exposed in the schema, which is a slight mismatch. 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 meaningful description is one concise sentence, front-loaded with the action and scope. The first line 'Update Location' is redundant with the tool name and title, which prevents 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?

Given the output schema, full parameter descriptions, and annotations covering idempotency and non-destructiveness, the description is largely sufficient. The only gap is that it does not clarify whether internal fields like slug and store_code are also updatable, but the schema covers those.

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

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

Schema description coverage is 100%, so parameters are already fully documented. The description's phrase 'public display and address details' helps map intent to display_name and address fields, but it does not add meaningful detail beyond the schema.

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

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

The description uses a specific verb ('Update') and resource ('project location') and narrows scope to 'public display and address details.' This clearly distinguishes it from create/location, deleteLocation, and listLocations. It does not explicitly name sibling tools, 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 description implies when to use the tool: whenever a location's display or address fields need changing. However, it provides no explicit guidance about when not to use it or which alternative to prefer, such as createLocation or updateReviewLocation.

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 supply idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds no behavioral context beyond the schema's boolean semantics, such as whether the existing flag is overwritten or whether any related state changes. It does not contradict the annotations, but it also does not enrich them.

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 readable, but the first line simply repeats the tool title and earns no additional value. The second sentence is compact and meaningful, keeping overall length appropriate, though the redundancy prevents a higher 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 two-parameter update tool with an output schema, the core action is adequately described. However, missing usage routing among sibling tools and any note about overwriting the existing flag value leave some contextual gaps. It is sufficient for straightforward invocation but not fully complete.

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 both 'id' and 'is_duplicate' already clearly documented. The description's word 'whether' adds minimal meaning over the boolean parameter description, 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 states a specific verb ('Mark') with a clear resource and property ('whether a review is a duplicate record'). This distinguishes it from sibling tools like updateReviewVisibility or updateReviewTags, which target different review attributes. It goes beyond the title by explaining the flag's meaning.

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

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

There is no guidance on when to use this tool versus alternatives. With many updateReview* siblings, the agent is not told that this tool is specifically for toggling duplicate status or when it should be preferred. Usage is only implied by the tool's name and a generic restatement.

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 it is not read-only, is idempotent, and is not destructive. The description adds valuable context: it uses active integration credentials, publishes to the platform, and accepts only manual text (no AI drafting). It also mentions that the reply is 'publish or replace', which is consistent with idempotency. No contradiction. The description does not mention potential side effects like rate limiting or platform-specific restrictions, but given it is idempotent and non-destructive, a 4 is appropriate.

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 one concise paragraph that front-loads the action and target. It wastes no words and packs key details into a few sentences. The phrase 'accepts manual reply text only and does not invoke AI drafting' efficiently communicates an important constraint.

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 two-parameter tool with 100% schema coverage and a clear description, it is nearly complete. An agent knows what to do, what parameters to provide, and what happens (publish or replace). Minor gaps: it doesn't mention how errors are handled (e.g., if credentials are invalid) or what the output schema contains, but the output schema likely covers that. The presence of an output schema reduces the need to explain return values. Overall, 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?

Schema description coverage is 100%, so both parameters are already described. The description adds context by explaining the 'reply' parameter is the text to post or update on the external platform, and it explicitly mentions the character limit (4000) which is also in the schema. It does not add extra meaning beyond the schema, but given full schema coverage, a baseline of 3-4 is appropriate; the 'publish or replace' clarifies the effect on existing replies.

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 action ('Publish or replace the business owner's reply'), the resource ('review'), and the target platform ('connected platform such as Google Business Profile or Facebook'). It distinguishes itself from sibling tools like 'markReviewReplied' by focusing on posting the actual reply text, and from AI drafting tools by specifying it only accepts manual text.

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

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

It implicitly explains when to use this tool: when you need to post or update a review reply on an external platform. It does not explicitly list alternatives or when not to use it, but the sibling context and the phrase 'does not invoke AI drafting' imply that other tools might be used for AI-generated replies. A clear 'when not to use' is missing.

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, destructive, and idempotency hints. The description adds useful behavioral context: it requires an existing project location and returns 404 if the slug is not found. It does not explain whether an existing review location is replaced, but the idempotentHint mitigates that gap.

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

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

The description is short and front-loaded with the core action, followed by the key error behavior. There is a minor redundant title line, but overall 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?

For a simple two-parameter tool with an output schema and informative annotations, the description provides the core operation, the lookup mechanism, and the main failure mode. It omits what happens when the review id is not found, but this is not a major gap given the schema and output schema.

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

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

Schema description coverage is 100%, so both parameters are already documented with meaningful detail. The description's 'by slug' phrasing adds no significant meaning beyond the schema's 'Slug of an existing project location' and its 404 note. 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 uses a specific verb ('Assign') and resource ('existing project location to a review by slug'), clearly distinguishing this from siblings like updateLocation or updateReviewSource. It also adds the 404 behavior for a missing location slug, reinforcing what the tool targets.

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 about when to use this tool versus alternatives such as updateLocation, updateReviewSource, or other review update tools. The purpose is implied, but the agent is left to infer the selection criteria from the name and description.

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/write safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds one useful behavioral detail: 'Returns 404 if the source slug is not found.' However, it does not disclose what happens to any previously assigned source or other side effects beyond the annotation baseline.

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

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

The core action and error behavior are expressed in two concise sentences. The only mild redundancy is the opening 'Update Review Source' line repeating the tool title, but the rest is front-loaded 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?

For a two-parameter tool with an output schema and safety annotations, the description covers the essential action, the requirement that the source already exists, and the 404 failure mode. It is sufficiently complete for an agent to know how to invoke the operation correctly, though it could note whether an existing assignment is replaced.

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 parameter descriptions already document id and source_slug. The description's mention of 'existing review source' and '404' largely repeats the schema's own text for source_slug, adding no new parameter-level meaning beyond what the input 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 operation: 'Assign an existing review source to a review by slug.' This clearly identifies the verb (assign), resource (review source), and target (review), and distinguishes it from sibling tools like updateSource (which modifies source settings) or createSource (which creates sources).

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 usage context is implied: use when you need to attach an existing review source to a review. However, it does not explicitly name alternatives or state when not to use this tool, unlike sibling tools such as updateSource or createSource, 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?

The description adds the key behavioral trait 'Replace' beyond what the annotations provide, signaling that existing tags not in the slug list will be removed. This aligns with idempotentHint=true and destructiveHint=false and is consistent with the schema note about clearing all tags with an empty array.

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 clear, front-loaded sentence with no filler. The only minor redundancy is repeating the title 'Update Review Tags' at the start, but the meaning-bearing sentence is efficient.

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

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

For a two-parameter mutation with 100% schema coverage, meaningful annotations, and an output schema, the description is complete. It covers the core operation, while the schema explains parameter details and the empty-array clear behavior. No critical information is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters, including the special empty-array behavior. The description only says 'using the provided slug list,' which adds no meaning 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?

The description states a specific verb ('Replace') and a clear resource ('tag assignments for a review'), and the sibling list shows it is distinct from updateCustomerTags and updateTag. 'Replace' also clarifies that this is not an incremental add operation, 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 intended use case is clear: to overwrite the tag assignments on a review. It does not explicitly name alternatives or exclusions (e.g., updateTag for editing tag definitions, updateCustomerTags for customers), but the 'for a review' scoping makes the context evident enough for correct 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 indicate that this is a write operation (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description adds the specific behavioral effect on 'public displays,' which is meaningful context beyond the annotations. 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 extremely concise: two short sentences that state the purpose without any fluff. It is front-loaded with the action and resource, and every word earns its place. There is no redundant information or padding.

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 (two required parameters, all documented in the schema, and an output schema available), the description covers the essential usage. It explains the effect on public visibility, and since an output schema exists, return values are not the description's responsibility. It is complete enough for an agent to call 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%—both parameters (id and is_hidden) have clear descriptions in the schema. The description adds a slight clarification by stating 'show or hide,' which maps to the boolean is_hidden parameter, but this adds little beyond what the schema already provides. 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 clearly states the purpose: 'Show or hide a review in public displays.' It uses a specific verb ('show or hide') and identifies the resource ('review' and 'public displays'). This distinguishes it from sibling tools like updateReviewLocation or updateReviewSource, as it focuses solely on visibility.

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 no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, conditions, or exclusions. While the purpose implies that this is for toggling visibility, an agent gets no explicit signal about when it should be chosen over other update tools (e.g., updateReviewDuplicateFlag).

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 provide the safety profile (non-read-only, non-destructive, idempotent), so the description only needs to add unique behavioral context. It discloses a useful failure mode: sending a sprite while a custom icon image is set returns an error. This is valuable beyond both the annotations and 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 body is two sentences with the action front-loaded and the edge-case warning placed after. The repeated 'Update Source' heading is slightly redundant, but the overall description is lean and readable.

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 five-parameter mutation with a full output schema and annotations, the description covers the operation and a key error condition without restating schema details. It could add explicit partial-update semantics or permission requirements, but those are not critical given the schema coverage and annotation support.

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 id, name, slug, color, and sprite formats, constraints, and clearing behavior. The description's field list mirrors the schema but does not add meaningful parameter-level semantics beyond the error condition, which is more of a behavioral warning.

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 clear verb–resource pair ('Update ... review source') and names the exact mutable fields: display name, slug, color, and sprite class. It does not explicitly contrast with createSource or updateReviewSource, but the field list and the word 'existing' make the tool's scope identifiable.

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 context by saying this is for an existing review source, which signals an update rather than a create or delete operation. It does not name alternative tools or explicitly state when not to use it, so it stops short of full routing guidance.

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

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

Annotations already carry the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the description needs only to add context. It adds 'existing' and the field focus, which is marginally useful, but it does not disclose partial-update behavior, slug-uniqueness conflict handling, or any workspace-level prerequisites for AI tagging. No contradiction with annotations, but little behavioral depth beyond what is structured.

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 definition is compact — a single useful summary sentence with minimal waste. It is slightly redundant in that the description opens by repeating the title ('Update Tag') before the substantive line, and it front-loads the purpose well. Efficient but with a small 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 tool with an output schema and 100% parameter coverage, the description adequately covers the operation's scope and the fields involved. The schema carries parameter details and return shape, so nothing essential is missing for an agent to call it correctly. Fails to earn a 5 only because it could note partial-update semantics or slug-uniqueness implications, though these are minor given the schema's richness.

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 every parameter (id, name, slug, color, sprite, has_ai_tagging, ai_instructions) in detail, including sprite format rules and length limits. The description's mention of the updatable fields (name, color, slug, AI tagging) offers only a light orientation and adds no syntax or meaning beyond what the schema provides. Baseline 3 is correct.

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 (rename/recolor/adjust) tied to a resource ('existing workspace tag') and lists exactly which aspects are modified: name, color, slug, and AI tagging settings. 'Existing workspace tag' clearly differentiates it from createTag and deleteTag, so an agent can pick it correctly without opening the schema.

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

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

The phrase 'existing workspace tag' implies this is for modifying tags that already exist, contrasting with the create/delete siblings, but the description never explicitly names createTag for new tags or states when not to use this tool. Usage context is implied rather than spelled out, with no explicit exclusion conditions or alternative routing.

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