Aura Historia MCP

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

Adds substantial context beyond the annotations: the default for the notifications field, that existing entries conflict, that tier quotas apply, and crucially that a timeout can leave the mutation outcome unknown and the watchlist must be inspected before retrying. None of that is derivable from readOnlyHint=false, idempotentHint=true, or destructiveHint=false.

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

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

Four short sentences, front-loaded with the action, then defaults, then conflict/quota behavior, then failure handling. Every sentence conveys an operational fact an agent needs.

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 an output schema available, the description covers the field default, conflict semantics, quota limits, and the ambiguous-timeout failure mode. Nothing material 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?

Schema description coverage is 0%, so the description must carry the load, and it does for the optional parameter: notifications defaults to enabled when omitted or null. productListingId is left to the schema's regex pattern, which is self-describing, but no prose explains what format is expected.

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

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

States a specific verb and resource: 'Add a listing to your watchlist,' which is immediately distinguishable from deleteWatchlistProduct, patchWatchlistProduct, and getWatchlistProductListings. It does not explicitly name a sibling or its boundary condition, 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?

Usage is implied by 'Add a listing to your watchlist' and the retry guidance ('inspect your watchlist before retrying') gives a concrete recovery path. However, it never says when to prefer patchWatchlistProduct instead of re-adding, nor states prerequisites explicitly, so guidance remains partly inferred.

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

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

Annotations already flag idempotentHint=false, and the description makes that concrete and actionable: every accepted call yields a new identity, so a blind retry after a timeout creates duplicates and the caller should reconcile first. It also discloses that the record is private, which is behavioral context not present in 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?

Two tight sentences, front-loaded with the action and immediately followed by the consequence model. 'Full submitted geography' is slightly jargon-y but no sentence is 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?

The output schema means return values need not be explained, and the non-idempotency is well covered. However, for a create tool with entirely undocumented parameters, the description should still clarify what label and referenceRelease are for.

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 0%, so the description must carry parameter meaning, yet it never mentions 'label' at all and only gestures at geography via 'full submitted geography'. It does not explain the required referenceRelease or the addressText length constraints, leaving the caller dependent on the raw 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?

'Create a private address bookmark with full submitted geography' gives a specific verb, resource, and scope, so it is clearly distinct from getUserAddress/updateUserAddress/deleteUserAddress. It does not explicitly name those siblings, but the operation itself is unambiguous.

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

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

The retry advice ('after an unknown outcome, reconcile your address book before retrying') is a useful operational guideline, but nothing states when to choose this over updateUserAddress or createUserSearchFilter, or any prerequisite such as needing an existing account or reference release.

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

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

Adds real context beyond the annotations: matching is scheduled and results are eventual (an asynchronous side effect not encoded anywhere in annotations), notifications default to true, and creation is non-idempotent so an unknown outcome must not be retried. This is exactly the kind of post-call hazard an agent cannot infer from readOnlyHint=false / idempotentHint=false 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?

Three short sentences, front-loaded with purpose, then defaults, then the async/retry hazard. No filler and nothing buried in the middle.

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 write tool with an output schema and adequate annotations, the description covers the critical unknowns: async matching latency and retry safety. It stops short on the search-criteria vocabulary and any permission/duplicate-name constraints, but nothing essential to calling it safely 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 0% and the `search` parameter is a large nested ProductListingSearchData object with dozens of undocumented fields (availability, orderability, geography, price ranges, ID patterns). The description only glosses the four top-level parameters by name ('complete criteria', 'optional shipping-destination acceptance', 'notifications default to true') and adds no field-level meaning, so it does not compensate for the coverage gap.

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

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

States a specific verb and resource: 'Create an own saved search', plus the scope of what is stored ('complete criteria and optional shipping-destination acceptance'). It is clearly distinguishable from the update/delete/get siblings by the verb alone, though it never names those siblings explicitly.

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

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

Usage is implied by the verb and by the sibling set (updateUserSearchFilter / deleteUserSearchFilter), but the description never says when to create versus update, whether duplicates are allowed, or what prerequisites exist. The non-idempotency warning is behavioral guidance rather than 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?

The annotations already declare destructive, idempotent, non-read-only, and closed-world behavior. The description adds meaningful context beyond them: deletion is permanent, only owned notifications can be deleted, missing or foreign IDs return not found, and success yields null.

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 three compact sentences, front-loads the destructive action and scope, and contains no redundant or wasted phrasing.

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 tool with annotations and an output schema, the description covers the essential behavior: permanence, ownership, not-found handling, and success shape. The main remaining gap is the lack of explicit routing to the bulk delete 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?

There is only one parameter and schema description coverage is 0%, so the description must carry weight. It names notificationId and adds ownership and not-found semantics, but it does not explain the required ID format beyond what the schema pattern 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 a specific verb and resource: permanently delete a notification. It also narrows scope to one owned notification, which distinguishes it from the sibling deleteNotifications bulk operation.

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 single-notification scope implies when to use this tool, but the description never names the alternative deleteNotifications or explicitly explains when to choose one over the other. The missing/foreign ID behavior is useful but is not usage guidance.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description still adds real value by stating the deletion is permanent and extends beyond the visible/listed page, which the annotations do not express, and it promises result:null on success.

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

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

Three short sentences, all load-bearing: scope and irreversibility are front-loaded, then the argument constraint, then the return value. Nothing is padded or redundant.

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

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

For a zero-parameter destructive bulk operation, the description covers scope, permanence, argument shape, and success signal; the return value is also documented by an output schema, so nothing material is missing.

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

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

With zero parameters the baseline is 4, and the description reinforces that no IDs may be supplied and the argument object must be empty, which guards against an agent hallucinating notification IDs. It adds a modest amount beyond the empty-object 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 definition states a specific verb and resource (delete the whole notification inbox) and uses "entire ... including items beyond the listed page" to make the bulk scope explicit, which implicitly separates it from the singular deleteNotification sibling. An agent can tell what will be removed 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 description implies the use case (wiping everything rather than the current page) but never names an alternative such as deleteNotification for single items or updateAllNotificationsSeen. There are no explicit when-not conditions or prerequisites.

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, and the description adds useful behavior: the browsing-destination side effect and the result:null success response. It still omits failure behavior, such as what happens when expectedVersion does not match.

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

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

Three short sentences, front-loaded with the delete action, followed by the side effect and success return value. There is no repetition or wasted prose.

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 output schema and annotations cover the return shape and safety profile, and the description adds the browsing-destination side effect. With two required parameters at 0% schema description coverage, missing parameter semantics and failure behavior leave meaningful 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 0%, so the description must compensate. It mentions expectedVersion but does not explain that it is a concurrency token, and it does not clarify addressId semantics, ownership requirements, or identifier format.

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

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

Names a specific verb and resource: delete an owned user address using its concurrency token. It is clear what the tool does, but it does not explicitly distinguish itself from sibling mutations such as updateUserAddress or createUserAddress.

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 'Delete the selected owned address' and the note about clearing a browsing destination when applicable. However, it gives no explicit when-to-use or when-not guidance and does not name alternative 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?

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description adds meaningful behavior: success returns null, and missing or other users' filters remain not found. It does not mention auth requirements or irreversibility explicitly, but the ownership/security scoping is valuable context.

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

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

Two short sentences, front-loaded with the core action and followed by the critical success/not-found behavior. 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?

With an output schema and rich annotations already present, the description covers the key behavioral nuance (own-search scoping and not-found handling). The main gap is parameter explanation, but overall it is sufficient for an agent to invoke this simple deletion 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 is one parameter with 0% schema description coverage. The description does not explain userSearchFilterId, its expected format, or its role beyond the name implying it; the cryptic regex pattern is left entirely to the schema.

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

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

States a specific verb and resource: 'Delete an own saved search.' This distinguishes it from sibling tools like deleteNotification or deleteUserAddress by clearly identifying the saved-search 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 'own saved search' implies that only user-owned filters can be deleted, and the not-found behavior reinforces this. However, it does not explicitly state when to use this versus alternatives such as updateUserSearchFilter or getUserSearchFilters.

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, yet the description adds genuinely new behavior: NOT_FOUND on a missing entry even after a prior successful removal, and the fact that a timeout leaves the mutation outcome unknown with a recommendation to inspect the watchlist before retrying. That is exactly the failure-mode context annotations cannot express.

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

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

Three short sentences, front-loaded with the action, then the error semantics, then the retry hazard. Nothing is redundant.

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

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

An output schema exists, so return values need not be explained, and the annotation set covers the safety profile. The description rounds this out with failure and retry semantics, though it says nothing about permissions or whether a removed listing can simply be re-added.

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 0% and the description never mentions productListingId, so no meaning is added beyond the schema. However, there is only one required parameter and its format is fully pinned by a strict regex pattern, so the practical gap is small.

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

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

States a specific verb and resource ('Remove a listing from your watchlist'), which cleanly distinguishes it from the add and patch watchlist siblings. An agent can identify the operation 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?

Usage is implied by the name and the removal verb, but there is no explicit guidance on when to prefer this over patchWatchlistProduct or when removal is appropriate versus merely updating. The guidance present is about error/retry handling rather than tool selection.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive, non-open-world operation. The description adds useful hints that results are public and use cursor pagination, but it does not explain pagination behavior, ordering, or limitations in any detail.

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 single sentence is front-loaded and has no filler, which is structurally efficient. However, it is too terse for a tool with a complex nested geography parameter and low schema description coverage, so it is not appropriately sized for the complexity.

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 output schema and annotations relieve some burden, but the input contract remains unclear: the required geography object has several undocumented fields and the cursor shape is not described. An agent could not confidently construct a non-trivial geographic query from this definition alone.

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

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

Schema description coverage is only 33%, with the nested geography object and searchAfter cursor effectively undocumented in the schema. The description loosely refers to 'complete geographic predicates' and 'cursor pagination' but does not explain how to populate mode, origin, radius, countries, subdivisions, distanceOrder, or the cursor fields.

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

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

The description states a clear verb and resource: discovering public party locations. It distinguishes the tool from most siblings by resource, but does not name or differentiate it from potentially related tools such as searchPublicListingSources or listAuctions.

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, when not to use it, or what prerequisites apply. The mention of geographic predicates implies a search use case, but the agent is left to infer that without explicit routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying that it returns 'complete public auction details' including source metadata, schedule, counts, and catalogue links, which goes 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 description is a single, front-loaded sentence that enumerates the returned data without any 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?

The output schema and annotations cover return values and safety respectively, so the description does not need to explain those. However, for a tool with a required ID parameter and sibling alternatives, the lack of usage guidance and parameter semantics leaves clear 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 0% for the single required auctionId parameter, and the description does not mention it at all. While the parameter name and regex pattern are self-explanatory in the schema, the description provides no added meaning such as where to obtain an auctionId or its format.

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

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

The description states a specific verb and resource ('Get complete public auction details') and enumerates what is returned (source metadata, schedule, counts, catalogue links). It clearly distinguishes the tool from list-type siblings by implying single-auction retrieval, though it does not explicitly name getAuctionCatalogue or listAuctions as alternatives.

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

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

The description provides no guidance on when to use this tool versus alternatives such as getAuctionCatalogue or listAuctions. It only describes the output, leaving the agent to infer the selection context.

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

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

Annotations already declare readOnly, idempotent and non-destructive, and the description adds genuinely new behavioral context the annotations cannot: the per-section OAuth read-scope requirement and the explicit warning that 'write scopes do not imply reads'. The 'stable catalogue continuation' phrase also signals stable pagination keys. It stops short of describing rate limits or what a missing-scope call returns.

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

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

Two tight sentences: the operation and its outputs come first, followed by the auth constraint an agent needs before calling. No filler, no repetition of the tool name.

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

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

With a rich output schema and full annotations, the description only needs to cover safety, auth and pagination semantics, which it largely does. The gap is parameter-level: pageSize bounds and cursor behavior are undocumented, and the userState mention is not backed by any schema property.

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 0%, so the description must carry the load. It explains currency and language as presentation controls and implies searchAfter is a continuation cursor, but leaves pageSize, the auctionId identifier format, and cursor lifetime undocumented. Note also that it references a 'userState' input that does not appear among the declared properties.

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

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

States a specific verb and resource ('Get public auction lots') and names the notable output dimensions (language, currency, shipping presentation, catalogue continuation). It does not explicitly differentiate itself from the sibling getAuction, so an agent must infer that this returns the paginated lot catalogue rather than a single auction.

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 useful invocation context through the scope rules for the optional userState path ('watchlist:read, search-filters:read...'), and 'stable catalogue continuation' implies paginate via repeated calls. However, it never says when to prefer this over getAuction or listAuctions, so the sibling routing is left 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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful domain context by naming the possible destination types and calling the destination 'versioned', but it does not add auth, rate-limit, or other behavioral details beyond what annotations and the output schema 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?

A single front-loaded sentence with no filler. The purpose and the possible values are stated immediately, and every clause 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 zero parameters, rich annotations, and an output schema, the description is nearly complete: it states the resource and the possible destination states. It does not elaborate on what 'versioned' means or when the destination changes, but those gaps are minor given the simplicity of the tool.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly does not waste space documenting parameters, and the empty input schema is fully covered by the schema itself.

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 (Read), resource (your versioned browsing destination), and enumerates the possible destination states: NONE, owned ADDRESS, or COUNTRY_POSTAL. This clearly distinguishes it from the mutation sibling setBrowsingDestination without requiring the schema to be opened.

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 verb 'Read' implies retrieval and the sibling setBrowsingDestination implies the write alternative, but the description never explicitly says when to use this tool versus alternatives, nor does it state any exclusions or prerequisites. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so the bar is lower; the description adds genuinely new context by spelling out the per-section read scopes needed for userState and warning that write scopes do not imply reads. It does not cover behavior when the ID is unknown.

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

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

Two tight sentences with zero filler; the core purpose and scoping key are front-loaded before the optional-parameter caveat.

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

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

An output schema exists, so return values need no explanation, and the read-scope requirement is covered. Gaps remain around not-found behavior and the missing userState parameter definition, given this is a public-detail read.

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

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

Schema description coverage is 0%, so the description carries more burden; it does clarify that productListingId must be the internal ID and what userState needs, but says nothing about how currency and language change the response (pricing/localized content). It also references a userState parameter that is absent from the input schema, leaving that structural mismatch unexplained.

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

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

States a specific verb and resource ('Get the complete public listing details') scoped by an explicit key ('internal ProductListing ID'), which cleanly separates it from getProductListingByTitleSlug, getProductListingHistory and getPublicOverview.

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 'by internal ProductListing ID' phrasing implicitly routes slug-based lookups to the sibling, and the scope sentence tells the agent what userState requires. It stops short of naming an explicit alternative or stating when not to use it.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's real contribution is the authorization detail: per-section read scopes for Aura userState, and the non-obvious rule that write scopes do not imply reads. It does not explain how userState is supplied, especially since no userState parameter exists in 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?

Two sentences, purpose front-loaded, no filler. The authorization sentence is dense but every clause carries information, even if the userState reference is cryptic without a corresponding parameter.

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

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

An output schema exists, so return values need not be described, and the safety profile is covered by annotations. Still missing: selection guidance versus getProductListing/getSimilarProductListings, and how the userState conditional is actually invoked given it is absent from the input 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 0% across three parameters. The description only adds meaning for one of them (the slug is immutable and identifies the listing), while currency and language - both enum-heavy with defaults - get no explanation of how they affect the returned listing.

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

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

States a specific verb and resource with the lookup key: 'Get the complete public listing details by its immutable title slug.' That distinguishes it in spirit from getProductListing (ID-based) and getPublicListingSourceBySlug, though those siblings are never named. Clear but not explicitly differentiated from siblings.

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

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

Usage is only implied: an agent can infer this is the slug-based read path and the section read-scope requirement is noted. There is no explicit statement of when to prefer it over getProductListing or what happens when the slug doesn't exist.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), yet the description still adds real behavioral value: no pagination because every event comes back in one call, results are in original event order, and oversized responses fail outright rather than truncating. The only gap is not naming what the failure looks like or the size threshold.

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

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

Two dense sentences with zero filler: the ordering/scope guarantee leads, the currency option follows, and the all-in-one-call/failure behavior closes. Nothing repeats the name or wastes a clause.

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 structure needn't be explained, and the annotations plus the all-or-nothing failure note cover the risk profile. What remains thin is parameter documentation (currency semantics only loosely defined, no size limit mentioned for the 'oversized' failure), keeping it just short of 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 0%, so the description has to carry parameter meaning. It partially does: 'optional per-event historical display currency' explains currency's role (a display-only, per-event conversion), which the bare enum cannot. However, productListingId gets no explanation beyond its regex pattern, so half the parameters remain semantically thin.

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

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

States a specific verb+resource ('Get the complete public listing history') with a clear scope modifier ('in original event order') and an optional presentation dimension (currency). It is distinguishable from getProductListing by the 'history' framing, but it never explicitly contrasts itself with that sibling, so an agent must infer the difference.

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

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

Usage is implied rather than stated: 'Returns every event in one call; oversized results fail explicitly' hints that this is the bulk/history path rather than the current-state path, but there is no explicit 'use this instead of getProductListing when you need change history' guidance and no exclusions or prerequisites.

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, non-destructive and closed-world, so the safety profile is covered. The description adds that the resource is 'public' (no user-scoped auth implied) and framed as a 'card', but says nothing about behavior when the slug is unknown or malformed (error vs null).

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

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

A single front-loaded sentence with no filler; the resource and the lookup key come first. It is efficient, though its brevity borders on under-specification rather than tight 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?

Output schema exists, so return shape need not be described, and the tool is a simple single-parameter read. Still missing is any note on where to obtain a canonical slug and how a not-found case surfaces, which an agent needs to chain calls 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 0%, so the schema only gives `listingSourceSlugId: string` with no meaning. The description partially compensates by clarifying that the expected value is a canonical slug rather than an arbitrary id, but it gives no format, source, or example of where such a slug comes from.

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 ('Read') and resource ('public listing-source card') plus the lookup key ('canonical slug'). It is clear what the tool returns, though it never names or distinguishes itself from the sibling searchPublicListingSources, which is the obvious alternative path to the same resource.

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

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

There is no explicit guidance on when to call this versus searchPublicListingSources, and no mention of the precondition that a canonical slug must already be known. The phrase 'by its canonical slug' only faintly implies the requirement.

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

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description still adds meaningful context beyond that: the data is 'stored' (i.e., precomputed/cached rather than live-computed) and comes with its own 'calculation time', which tells the agent how to judge freshness — a real behavioral disclosure.

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

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

A single front-loaded sentence with no filler. The two facts the agent needs (what is returned, and that a calculation timestamp accompanies it) are both present and neither is padded.

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

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

With an output schema present, the description need not enumerate return fields, and with zero parameters there is no input to explain. The only remaining gap is the vagueness of 'aggregates', which the output schema presumably resolves.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The schema being fully described and parameter-free means no semantic gap remains.

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

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

It names a specific verb ('Read') and a resource ('stored public catalogue aggregates and their calculation time'), so the agent knows it is a retrieval of precomputed catalogue data. However, 'aggregates' is left undefined — the agent cannot tell what metrics or dimensions are covered, nor how this differs from sibling tools like getAuctionCatalogue or getPublicListingSourceBySlug.

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

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

There is no statement of when to call this versus the many catalogue/listing siblings, and no prerequisites or exclusions. The agent must infer usage purely from the resource noun.

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

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

Adds real context beyond the readOnly/idempotent annotations: an asynchronous state machine (EMBEDDING_PENDING vs READY), the possibility of a legitimate empty result, and per-section read-scope requirements with the caveat that write scopes do not imply reads. This is meaningful behavioral disclosure that annotations cannot express.

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

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

The purpose and state-handling sentences are dense and front-loaded with no filler. However, the trailing auth-scope sentence refers to a structure absent from the schema, so a full third of the text is spent on something the caller cannot act on.

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

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

An output schema exists, so return shape need not be explained, and the state handling is covered. But for a tool with 0% schema coverage on three parameters including a strict ID pattern, the description leaves the caller dependent on raw schema inspection and adds an irrelevant auth note.

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 0% and the description documents none of the three actual parameters — currency, language, and the regex-constrained productListingId are left entirely to the schema. Worse, it references an 'Aura userState' concept that does not appear as a parameter in the input schema, which misleads more than it clarifies.

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

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

States a specific verb and resource ('Find similar public listings') plus the scope constraint of the fixed service neighbor limit. It is distinguishable from getProductListing and simpleSearchProductListings by the word 'similar', but it never names or explicitly contrasts the nearest siblings, 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?

Gives useful state-driven guidance — retry on EMBEDDING_PENDING, empty list is valid on READY — but never says when to choose this tool over getProductListing, simpleSearchProductListings, or searchPublicListingSources. Usage is implied rather than directed.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and a closed-world scope, so the safety profile is fully covered. The description adds the scope of what is returned ('complete account and profile preferences'), but says nothing about auth requirements, rate limits, or whether the payload can be large. That is adequate but not rich given the annotations do most of the work.

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

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

A single front-loaded sentence with no filler. The scope word 'complete' is the only qualifier and it earns its place by signalling that the response is a full profile rather than a partial view.

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

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

With zero parameters, rich read-only annotations, and an output schema that covers return values, the description only needs to establish resource and scope, which it does. A brief note that it returns the authenticated caller's own account (not another user's) would close the remaining gap, but the essentials are present.

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

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

The tool takes zero parameters, so there is nothing beyond the schema to explain and the baseline of 4 applies. The description's only implicit parameter-like semantic is that the target is always 'your' account, which is consistent with the empty arguments object.

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 pairs a specific verb (Read) with a specific resource (your Aura account and profile preferences), so an agent can tell this apart from the mutating updateUserAccount and from narrower getters like getUserAddress or getUserSearchFilter. It does not explicitly name a sibling, which keeps it just 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?

Usage is only implied: 'Read your complete Aura account' suggests fetching the caller's own profile rather than an address or search filter. There is no explicit when-to-use, no statement of prerequisites, and no routing to alternatives such as getUserAddress for address data.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context: the record must be *owned* by the caller (an authorization constraint) and the response carries "complete resolution geography and source attribution." It omits what happens when the ID is not owned or not found.

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

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

A single front-loaded sentence with no filler; the verb and scope come first and the return-content clause follows. Slightly dense phrasing ("complete resolution geography and source attribution") costs a little clarity.

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

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

With an output schema present, return values need no explanation, and annotations carry the safety semantics. Combined with the ownership constraint and content summary, this is nearly complete for a one-parameter read tool; only error/permission behavior is left implicit.

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 0%, so the description must compensate; it does so only partially by implying the addressId must reference an address the caller owns. The regex pattern in the schema conveys the ID format, but nothing explains ownership failure modes or that the ID is a uaddr_ prefixed 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?

States a specific verb ("Read") and a precisely scoped resource ("an owned private address"), which separates it from sibling tools like listUserAddresses or getPublicOverview. It doesn't explicitly name a 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?

Usage is only implied: "owned private address" with a required addressId signals a single-record lookup, and the contrast with list/create/delete/update address siblings is inferable. No explicit when-to-use or when-not-to-use guidance, and no named alternative is given.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the useful detail that the response includes criteria, state and notification settings, but says nothing about not-found/unauthorized outcomes or whether settings are permission-gated.

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

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

A single front-loaded sentence with no filler. Minor awkwardness in 'an own saved search' slightly reduces polish but nothing is wasted.

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

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

With an output schema present, return values need no explanation, and for a one-parameter read tool the description covers the essentials. Missing only error/ownership semantics, which is a modest 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?

There is only one parameter and schema coverage is 0% – the schema exposes a strict regex but no prose explaining that userSearchFilterId identifies a filter owned by the caller. The description never references the id, so it does not compensate for the coverage gap, though the regex itself supplies format clues.

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

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

States a specific verb and resource ('Get an own saved search') and enumerates what is returned (criteria, state, notification settings). It reads as the singular counterpart to the sibling getUserSearchFilters, though the description never explicitly contrasts the two.

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 single-record phrasing implies 'use this when you have one filter id', but there is no explicit when-to-use, no pointer to getUserSearchFilters for listing, and no note about behavior when the id is not owned by the caller.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds that results include complete criteria plus state and notification settings, which is useful scope information, but it says nothing about ordering, count or pagination behavior.

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

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

A single sentence with zero filler, front-loaded with the verb and resource and followed by the payload scope. Nothing in it is redundant or buried.

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

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

An output schema exists, so return values need not be spelled out, and annotations cover the safety and idempotency profile. Combined with a parameterless schema, the definition gives an agent enough to call it correctly; only the sibling routing story is thin.

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

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

The tool takes no parameters, so the baseline is 4 and the description correctly implies a no-argument, full-list retrieval. There is no parameter information to get wrong or omit.

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 (own saved searches) and says it returns full criteria, state and notification settings. It implicitly separates itself from the singular getUserSearchFilter, but never names that sibling outright, so the differentiation is left for the agent to infer.

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

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

There is no explicit when-to-use, when-not-to-use, or alternative routing. 'own saved search' hints that this is scoped to the authenticated user's filters, but nothing tells the agent whether to call this or getUserSearchFilter/getUserSearchFilters-adjacent siblings in a given situation.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description only needs to add operational context — and it does: it discloses that results include personalized details and notification settings, and gives the pagination round-trip rule (JSON-encode the returned searchAfter for the next request). It does not mention authentication requirements, which is a small 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?

Three short sentences, front-loaded with the purpose and followed by the pagination protocol. Slightly padded by the marketing-leaning "complete personalized" phrasing, but no sentence is wasted.

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

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

With an output schema present, return values need not be described, and annotations cover safety. What is left thin is the parameter surface: size is undocumented anywhere, and prerequisites (the user must have a watchlist / be authenticated) go unstated for what is a personalized, user-scoped read.

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

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

Schema description coverage is only 25%, so the burden falls on the description, which only says "supports language, currency and pagination" without explaining defaults, enum constraints, or what size controls. The one substantive addition is the searchAfter round-trip instruction, though the schema itself already says it is JSON-encoded [RFC3339 timestamp, ProductListing ID]. Partial compensation, not full.

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

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

States a specific verb and resource ("List your watchlist") plus the payload (personalized listing details and notification settings), which cleanly separates it from the single-item getProductListing and from the add/delete/patchWatchlistProduct mutations. It never names a sibling explicitly, 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 context of use is implied by "your watchlist" and the pagination note, but there is no explicit when-to-use/when-not guidance and no named alternative (e.g. pointing to getProductListing for a single item). An agent can infer the case but is not routed.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds useful scope ('public auctions only') and mentions continuation filters, but never explains how pagination continuation actually works (searchAfter round-trip, pageSize limits) or what defaults apply.

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

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

A single front-loaded sentence with no filler, and the resource type leads. It is dense to the point of being a facet list rather than prose, but every clause maps to a real capability.

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

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

For a 10-parameter, fully optional query tool with an output schema and complete safety annotations, the description covers the filter surface, sorting and continuation adequately. Remaining gaps (enum meanings, pagination contract) are modest given the structured fields available.

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 0% across 10 parameters, so the description must compensate. It does name roughly seven of them in compressed form (listingSourceId, format, reportedStatus, from/to plus timeRole as 'exact schedule range', sort, continuation), but leaves order, pageSize and the four timeRole enum meanings unexplained.

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

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

The description opens with a specific verb+resource ('List public auctions') and enumerates the filter facets, so the agent knows this is a directory-style browse over public auctions. It does not differentiate against siblings like getAuction or searchPublicListingSources, which keeps it out of 5 territory.

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: this is the browse/list entry point, with filtering and continuation. There is no explicit when-to-use versus getAuction (single fetch) or the search tools, and no stated prerequisites or exclusions, so the agent must 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 disclose read-only, idempotent, non-destructive, closed-world behavior. The description adds useful context about honoring sensitive-content preferences and using searchAfter to continue pagination, though it does not mention auth requirements or rate limits.

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

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

The description is three sentences and front-loads the primary purpose before pagination details. However, the size default/clamp sentence duplicates schema text and could be trimmed.

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

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

An output schema exists, so return-value details are not required. The description covers purpose, language context, sensitive-content behavior, and pagination continuation, which is sufficient for a read-only listing tool, though it omits ordering or scope details.

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

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

Schema description coverage is 67%. The size behavior is repeated almost verbatim from the schema, and the searchAfter note largely restates the schema's JSON-string requirement while adding the continuation purpose. The description adds some value but does not fully compensate for the remaining schema gaps.

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: list notification inbox payloads and listing snapshots. It is clear what the tool retrieves, though it does not explicitly contrast itself with sibling tools such as deleteNotification or updateNotificationSeen.

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 'notification inbox' and the pagination instruction, but the description does not state when to use this tool instead of sibling notification tools. No explicit exclusions or alternatives are provided.

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 this as a safe, read-only, idempotent operation, so the description adds the important behavioral caveat that scheduled matching and projections are eventual. It also explains ascending match order and continuation via searchAfter, though it does not discuss permission requirements beyond implying ownership.

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

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

Two dense sentences front-load the core purpose and then add the key operational caveat. Every clause contributes useful information without repetition.

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

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

For a read-only listing tool with an output schema and rich annotations, the description covers purpose, ordering, pagination, and eventual-consistency behavior well. It could be slightly more complete by explicitly tying userSearchFilterId to the saved-search identifier, but the essentials are present.

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?

With only 20% schema description coverage, the description usefully adds meaning beyond the schema by naming language, currency, and JSON searchAfter continuation. It implies userSearchFilterId via 'own saved search' and omits size, but the schema already documents size and enumerations are self-describing.

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

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

The description states a specific verb and resource: list materialized matches for an own saved search. It also adds scope and ordering detail, making it clearly distinguishable from sibling filter-management tools such as getUserSearchFilter or updateUserSearchFilter.

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 makes clear that this tool is for retrieving matches of an existing saved search and warns that an empty page does not mean background matching is complete. It does not explicitly name alternatives such as fetching the filter definition itself, but the usage context is clear.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior. The description adds useful operational detail beyond that: continuation via the previous response's next token and the limit default/range. No contradiction is present.

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

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

Two sentences, front-loaded with the main action and then pagination; no filler. The phrase 'resolution and source attribution' is slightly dense but still earns its place.

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

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

With an output schema and rich annotations, the description only needs to cover listing scope and pagination. It does so adequately, though it omits ordering or whether archived addresses are excluded.

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 0%, so the description must carry parameter meaning. It does explain both after and limit, including continuation and limit defaults, but leaves the after token format and invalid-token behavior implicit; the stated limit default (25) also differs from the schema's null default.

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 opens with a specific verb ('List') and resource ('your private addresses'), and the plural framing differentiates it from the singular getUserAddress. It also hints at returned fields ('resolution and source attribution'), though it does not explicitly name a sibling as the alternative.

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 explains how to paginate but gives no guidance on when to use this list endpoint rather than getUserAddress or another address-related sibling. Usage is only implied by 'List your private addresses'.

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 mutation's destructive and idempotent nature, but the description adds valuable operational context: partial update semantics ('Omitted fields stay unchanged'), invalid null values, tier quotas on activation, and timeout uncertainty with a retry recommendation. These details go beyond structured annotations and help an agent avoid common pitfalls.

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

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

The description is front-loaded with the core action and every sentence adds distinct value: partial update behavior, validation, quota constraints, and timeout handling. There is no filler or repetition, and it is appropriately sized for a mutation tool.

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

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

Given the presence of annotations and an output schema, the description covers the essential behavioral aspects (partial update, validation, quota, timeout) needed to invoke the tool correctly. It only misses explicit mention of the required productListingId and any permission prerequisites, but otherwise is 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 0%, so the description must carry parameter meaning. It clarifies the purpose of notifications, state, currency, and language fields, but it never explains the required productListingId parameter or its format, leaving a gap for a critical input.

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 ('Update') and specifies the resource (watchlist notification setting or state) and the return (personalized listing). It distinguishes the patch operation from siblings like addWatchlistProduct and deleteWatchlistProduct by focusing on modification, though it doesn't name those siblings explicitly.

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

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

The description implies usage by stating what can be updated and constraints (e.g., omitted fields unchanged), but it never explicitly says when to use this tool versus alternatives like addWatchlistProduct or deleteWatchlistProduct. An agent must infer the appropriate context from the verb.

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, non-destructive, closed-world behavior, so the description only needs to add the parts annotations cannot express — and it does, disclosing cursor pagination bound to the query and page-size limits. It still omits how continuations are obtained, which the schema alone 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?

A single front-loaded sentence with the browse-vs-search distinction first and the pagination constraint second. Nothing is wasted and nothing important is buried.

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

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

With an output schema present and rich annotations, the description only needs to cover input behavior and query semantics, which it largely does for query and size. It leaves the cursor parameter and the size-bound discrepancy unresolved, a real but narrow 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 coverage is 67% and the description maps roughly onto that: it restates the 1–50 page-size range and the name-based query but adds no meaning beyond the schema. The undocumented searchAfter cursor, the most error-prone parameter, is untouched, and the stated 1–50 range sits uneasily against the schema's declared 0–255 bounds.

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

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

A concrete verb-plus-resource statement: "Browse or search public listing sources by name" tells an agent exactly what is enumerated and that filtering is name-based. It does not explicitly distinguish itself from the sibling getPublicListingSourceBySlug, which retrieves a single source, 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?

"Browse or search" plus "by name" implies that omitting the query browses and supplying text searches, but the description never states that condition or names the single-source sibling as the alternative for a known source. Usage is inferable rather than prescribed.

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 this as destructive and idempotent, but the description adds meaningful context: NONE clears the destination, ADDRESS must belong to the caller, and expectedVersion is used as a concurrency control. It still does not explain what happens on version mismatch, so it is not fully transparent.

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, starting with the core action and then clarifying the destination modes. Every clause earns its place by explaining a required variant or 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?

Given the output schema and annotations, the description is largely complete: it covers the mutation, clearing behavior, ownership constraint, and all destination variants. It could be stronger by explaining expectedVersion acquisition or conflict behavior and by explicitly routing reads to getBrowsingDestination, but it 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?

Schema description coverage is 0%, so the description must carry the burden. It explains the discriminated destination variants well, including that NONE clears, ADDRESS must belong to the user, and COUNTRY_POSTAL accepts an optional postalCode. It only names expectedVersion without explaining where to obtain it or how conflicts are handled, leaving a gap.

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

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

The description states a specific verb and resource: "Set or clear your browsing destination." It also names the destination modes, making the mutation purpose clear. It does not explicitly distinguish itself from the sibling getBrowsingDestination tool, 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?

It gives useful per-mode guidance for NONE, ADDRESS, and COUNTRY_POSTAL, which implies how each destination variant is used. However, it does not explicitly say when to use this tool versus getBrowsingDestination, nor does it state exclusions or prerequisites beyond the ADDRESS ownership constraint.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds important auth scope requirements for optional Aura userState and clarifies that write scopes do not imply reads, which is non-obvious. It also hints at FX-bound continuation, though it does not explain pagination limits or error behavior.

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

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

Two sentences, front-loaded with the main action, no wasted words. However, jargon like 'Aura userState' and 'FX-bound continuation' could be clearer, and the auth scope sentence is dense.

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 complex 22-parameter search tool with low schema coverage, the description is far too sparse. It omits parameter explanations, usage guidelines, and differentiation from siblings, leaving the agent with insufficient information to construct a correct query.

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

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

Schema description coverage is only 5% for 22 parameters, and the description does not explain any individual parameter. It vaguely references 'catalogue filters, presentation, sorting and FX-bound continuation' but provides no detail on fields like price, currency, shipping, geography, or availability. It also mentions a 'userState' parameter that is not in the schema, causing confusion.

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 (Search) and resource (public listings) and mentions filters, sorting, and continuation. However, it does not differentiate from sibling tools like searchPublicListingSources or getSimilarProductListings, and the term 'simple' in the name conflicts with 'complete catalogue filters' in the description.

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

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

No explicit when-to-use or when-not-to-use guidance; no alternatives are named. It implies use for public listing searches but leaves the agent to infer when to choose this over sibling search 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is known. The description adds real value on top: it discloses the full-inbox blast radius including unlisted items and states the success return (result:null). It stops short of warning that flipping seen=false wipes read state across the whole account with no undo.

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

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

Two sentences, no filler, with the scope constraint front-loaded and the return value relegated to a trailing clause. Every clause 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-boolean bulk mutation this covers scope, effect and success response, and an output schema exists so return structure is not required. Minor gap: no mention of permission requirements or how it affects unread counts elsewhere in the UI.

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 0% and the lone parameter has no description in the schema, so the description must carry it. It does tie 'seen' to its concrete effect — the boolean is applied to every notification — which is more than the schema offers, though it does not spell out the semantics of true vs false.

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

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

States a specific verb (Set) and resource (seen) with an explicit blast radius: 'every notification in your entire inbox, including items beyond the listed page.' This scope statement alone separates it from updateNotificationSeen (single) and updateNotificationsSeen (listed subset) without needing to name them.

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

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

The phrase 'every notification in your entire inbox, including items beyond the listed page' implies when this tool is appropriate versus page-scoped siblings. However, no sibling is named and there is no explicit when-not guidance (e.g. don't use for a single notification).

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 mutation and idempotency profile, but the description adds useful behavioral context: ownership scoping ('owned notification'), not-found behavior for 'Missing or foreign IDs,' and 'result:null on success.' It does not explain the destructiveHint or why setting seen is treated as destructive, but it meaningfully supplements 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?

Three short sentences, front-loaded with the operation and scope, followed by error and return behavior. Every sentence carries information an agent can act on.

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

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

For a simple two-parameter mutation with annotations covering safety and an output schema covering returns, the description is largely complete: it covers ownership, missing/foreign ID handling, and success signaling. The only notable gap is the semantics of the seen boolean.

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 0%, so the description must compensate. It adds ownership meaning to notificationId, but it does not explain the required boolean 'seen' parameter or clarify that it can set the notification unseen as well as seen, leaving one of two parameters semantically thin.

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

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

States a specific verb and resource: 'Set seen on one owned notification identified by notificationId.' The word 'one' implicitly distinguishes it from bulk siblings such as updateNotificationsSeen and updateAllNotificationsSeen, though those alternatives are not named explicitly.

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

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

The description implies single-notification usage through 'one owned notification,' which contrasts with bulk update tools. However, it never explicitly states when to choose this over updateNotificationsSeen or updateAllNotificationsSeen, leaving the routing to inference.

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

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

Annotations already declare idempotentHint=true and destructiveHint=true, so the safety profile is partly covered. The description adds genuinely useful behavior beyond that: deduplication of duplicate IDs, silent ignoring of missing or foreign IDs, and a null return with no per-item reporting — all of which affect how an agent interprets success.

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

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

Three tight sentences, front-loaded with the action and immediately followed by constraints and return behavior. No filler and nothing buried.

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

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

An output schema exists and the description still clarifies the return shape (result:null, no per-item reports), and mutation edge cases are covered. The notable omission is any framing of how this relates to its singular and all-notifications siblings, which matters given destructiveHint=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 description coverage is 0%, so the description carries the burden. It does well on notificationIds (at least one required, duplicates deduplicated, missing/foreign ignored), but the 'seen' boolean is never explained — whether false unmarks as unseen is left to inference.

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

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

States a specific verb and resource ('Set seen on selected notificationIds') plus scope ('in your inbox'). The word 'selected' implicitly distinguishes it from updateNotificationSeen (single) and updateAllNotificationsSeen (all), but it never names those siblings explicitly, so an agent must infer the distinction.

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

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

The description implies a batch-selected use case, but gives no explicit when-to-use rules and never names updateNotificationSeen or updateAllNotificationsSeen as the alternatives. The agent can guess from 'selected' but must reason it out rather than being routed.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds the genuinely useful PATCH contract — true/false sets, null clears, omission preserves — and the no-upsert rule for missing/stale matches. It leaves unstated what ownership enforcement ("own") implies for auth failures, but the behavioral core is well covered.

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

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

Two tight sentences, with the action and its three-state semantics front-loaded and the no-upsert caveat last. No filler and no restatement of the tool name.

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

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

An output schema exists so return values need no explanation, and annotations carry the safety profile. Combined with the patch semantics, the definition is nearly self-sufficient; only the meaning of ownership enforcement and the outcome for a rejected stale match are left implicit.

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 0% and the feedback parameter is an opaque $ref to PatchValue_boolean, yet the description fully disambiguates the three-state semantics of that field (set, clear via null, preserve via omission). The identity parameters are conveyed through the "existing own saved-search match" phrasing and their regex patterns already pin the format.

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

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

States a specific verb and resource: patch feedback on an existing saved-search match, scoped to the caller's own records and identified by filter plus listing. This clearly separates it from updateUserSearchFilter, listSearchFilterMatches and patchWatchlistProduct 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 establishes the applicable context (an existing, own saved-search match) and an explicit exclusion: missing or stale matches are not created, so the agent knows this is not an upsert path. It stops short of naming a sibling alternative to use when the match does not exist, which keeps it from a 5.

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

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

Annotations already declare the safety profile (destructiveHint=true, idempotentHint=true, readOnlyHint=false), and the description adds genuinely non-redundant semantics: omitted fields are preserved, explicit null clears nullable fields, and the sensitive-content boolean rejects null. What it omits is the consequence of destructiveHint=true (e.g., that clearing name/language fields is irreversible without a follow-up call) and any auth/scope requirement.

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

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

Three short sentences, zero filler, with the core purpose front-loaded and the patch/clearing rules immediately after. Every clause carries information the agent cannot get from annotations or the schema.

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

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

Output schema exists, so return values need no explanation, and the patch semantics plus the null constraint cover the main traps for a 0-required-param mutation tool. The gap is around scoping and side effects of a destructive-flagged update — an agent still cannot tell whether this affects only the authenticated user or what permissions are needed.

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 0%, so all six parameters rely on the description, which supplies the crucial global patch rule and a carve-out for showUnassessedOrSensitiveContent ("cannot be null"). The remaining five fields (firstName, lastName, language, currency, measurementUnit) get no per-field meaning, though their names and the enum sets are largely self-explanatory. Partial compensation, not full.

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

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

States a specific verb+resource pair ("Update your profile and preferences") that maps unambiguously to the account resource, and "your" makes clear it targets the caller's own account rather than another user. It does not explicitly differentiate itself from patch-style siblings like updateUserAddress or updateUserSearchFilter, but the resource distinction is obvious from the name and 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?

Describes the patch contract ("Omitted members are unchanged; null clears optional values"), which implicitly tells the agent how to invoke it, but never states when to prefer this over siblings such as getUserAccount for reads or updateUserSearchFilter for filter edits. No prerequisites or exclusions are given; usage is inferable rather than stated.

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

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

Annotations already declare destructive=true, idempotent=true and closed-world, so the safety bar is met. The description adds genuinely new context: identity and owner are immutable, and the write is versioned via expectedVersion — although it omits what happens on a version mismatch (conflict error vs. silent overwrite).

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

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

Two sentences, front-loaded with the action and scope, then a constraint. 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. What remains thin is the geography object's structure and conflict behavior, but the essential picture of a replacement-based, version-checked mutation is present.

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 0%, so the description must carry the load. It gives real meaning to expectedVersion (a concurrency guard) and names label and geography, but says nothing about the required nested referenceRelease, the addressText constraint, or the addressId format.

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

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

States a specific verb and resource: replace the label and geography of an owned address. It implicitly separates itself from createUserAddress/deleteUserAddress by scoping to an existing owned address, but never names a sibling to sharpen the boundary.

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

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

Usage is implied by 'owned address' and 'expectedVersion', which points at an optimistic-concurrency update flow, but there is no explicit when-to-use versus alternatives such as createUserAddress or deleteUserAddress, and no stated preconditions (e.g. address must exist and be owned).

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

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

Annotations already flag destructiveHint=true, idempotentHint=true, readOnlyHint=false, and the description earns credit for explaining the destructive semantics (nulls clear values, nested omission preserves) plus the async consequence ('matching remains scheduled and eventual'). It does not cover auth/ownership checks, which is a modest gap given a destructive mutation.

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

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

Four tight sentences, front-loaded with the purpose, each carrying distinct behavioral information. No filler, though the dense patch-semantics phrasing could be slightly more structured.

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

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

Output schema exists and annotations carry the safety profile, and the description covers patch semantics and the async behavior. However, for a destructive mutation over a deeply nested schema, the many search fields and the meaning of the 'own' ownership precondition remain unexplained.

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 0% and the schema is a large nested structure, so the description carries real burden. It compensates well for the tricky parts—nested omission/null-clearing semantics and the required co-patching of availability/orderability/includeUnspecifiedAvailability—but does not explain the top-level parameters (name, state, notifications, acceptShippingDestination) or the many nested search fields.

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

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

States a specific verb ('Patch') and resource ('own saved search'), clearly distinguishing it from the get/create/deleteUserSearchFilter siblings. The 'own' qualifier adds an ownership scope that further disambiguates it. It stops short of naming an alternative sibling explicitly, but the operation is unambiguous.

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

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

'Patch' implies partial-update usage versus the create/delete siblings, and the patch-semantics sentences hint at when this is appropriate. However, there is no explicit 'use this when / not when' guidance or named alternative, so usage must be inferred.

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