EventWave

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false. The description adds the domain coverage (discovery, promotion, evidence, payment) and 'machine-facing' scope, but it does not disclose what the returned capability description actually contains or how it is structured. No contradiction with annotations.

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

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

One compact sentence with no filler. It leads with the verb and resource, then enumerates the relevant domains. Although the phrasing is dense, it is appropriately sized for a zero-parameter discovery 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?

The tool is simple and annotations cover its safety profile well, but no output schema exists and the description does not explain what the response will look like. The word 'boundaries' is never concretely defined, leaving some ambiguity about the exact information an agent will receive.

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

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

The tool has zero parameters, so the schema carries no parameter burden; the baseline is 4. The description's mention of specific boundary domains adds useful context even though no parameter documentation is needed.

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

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

The description uses a specific verb ('Describe') and identifies the resource: EventWave machine-facing boundaries across discovery, promotion, evidence, and payment. It is distinguishable from the sibling tools, which handle specific offers, statuses, checkouts, and handoffs; however, 'boundaries' is somewhat abstract and could be more concrete.

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 tool versus its siblings. The description only implies that it provides capability/boundary information, but it never states 'call this before exploring other EventWave tools' or excludes cases where the other tools should be used instead.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description goes further by explicitly stating it 'creates no checkout, invoice, charge, or payment obligation.' This adds concrete behavioral context beyond the structured hints, reassuring the agent about side-effect-free invocation.

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 tightly packed sentences: the first states the action and scope, the second reinforces safe read-only behavior. No filler, no repetition of schema or annotation fields, and the key detail is front-loaded.

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 parameterless list operation with strong annotations and a simple output expectation, the description covers everything an agent needs: what is listed, that it is current, and that no financial obligation is created. No output schema exists, but the task is simple enough that no additional return–format details are required.

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

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

The tool has zero parameters)Skip the input schema is empty and schema coverage is trivially 100%. With no params, there is nothing the description needs to explain; the baseline of 4 applies.

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

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

The description opens with the verb 'List' and identifies the exact resource: 'current EventWave paid promotion packages'. Adding 'evidence/payment boundaries' clarifies the scope and distinguishes this from siblings like get_eventwave_promotion_status or prepare_event_promotion_checkout.

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: it lists current paid promotion offers, and the read-only disclaimer suggests using this when no side effects are desired. However, the description does not explicitly name alternatives or state when not to use this tool, so an agent must infer routing from sibling names.

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

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

Beyond the readOnlyHint annotation, the description discloses that the tool may advance an internal verified payment state, a non-obvious side effect that an agent would otherwise miss. It also clarifies that it is read-only from the agent perspective, reconciling the annotation with the internal state change. This adds significant behavioral nuance.

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, each earning its place: the first states the primary action and condition, the second clarifies read-only semantics and the internal side effect. No fluff; the key information is front-loaded.

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

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

For a tool with no output schema, the description does not explicitly describe the returned 'promotion order state' or the verification result. It gives enough context to guess, but an agent would be unsure of the exact output shape, edge cases (e.g., no checkout session), or error behavior. The description is adequate but leaves 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?

With 0% schema description coverage, the description carries the burden for explaining order_id. It only implies the parameter through 'promotion order state' and 'checkout session', but never explicitly states what order_id refers to, its source, or format. The inference is possible but the description fails to compensate for the schema 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 uses specific verbs ('Read', 'verify') on a clear resource ('promotion order state', 'payment'), and distinguishes this from sibling tools like prepare_event_promotion_checkout and search_events by focusing on status/verification. The title adds 'payment and placement status', and the description further specifies the independent verification behavior, making the tool's purpose unmistakable.

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 a clear usage context: read order state and verify payment, especially when a checkout session exists. However, it does not explicitly contrast with sibling tools or state when not to use it, so it lacks explicit exclusions/alternatives.

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

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

Annotations indicate this is a non-read-only, non-destructive operation. The description adds the important behavioral caveat that checkout creation is not payment proof and that source review controls public placement. This goes beyond the annotations by clarifying the side-effect implications, but it omits details like whether the operation is idempotent (annotations say false) or any required authorization 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 two sentences with no waste. It front-loads the purpose and condition in the first sentence and adds a critical caveat in the second. Every sentence earns its place.

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

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

With 10 parameters, no output schema, and no parameter descriptions, the description is too brief to fully guide an agent. It does not explain what the checkout response contains (e.g., URL or ID), nor does it mention any prerequisite steps like selecting an offer first (implied by siblings). The caveat is helpful but does not compensate for missing operational 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 0%, so the description must compensate by explaining parameters. It only hints at 'selected EventWave promotion package' which loosely maps to offer_key, and 'human explicitly agrees to pay' maps to user_confirmed_payment. It does not explain contact_email or any of the optional fields like city, venue_name, or target_url. With 10 parameters and no schema descriptions, this is a significant 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 clearly states the tool's purpose: to prepare a secure checkout for an EventWave promotion package after human confirmation. The verb 'prepare' and resource 'checkout' are specific, and it distinguishes itself from read-only siblings like get_eventwave_promotion_offers by emphasizing the human-confirmed payment context. However, it does not explicitly name an alternative tool for comparison, which prevents a 5.

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

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

The description gives a clear prerequisite: 'After the human explicitly agrees to pay'. This tells an agent when to invoke the tool. However, it does not mention when not to use it or contrast with alternatives like prepare_event_promotion_handoff or the get_* tools. The caveat about checkout creation not being payment proof is useful but does not serve as 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying exactly what it does not do (create checkout, invoice, charge, entitlement, payment obligation) and emphasizing the human-in-the-loop requirement. This goes beyond the annotations and clarifies the tool's side-effect-free nature.

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 exactly two sentences: the first states the core purpose, the second clarifies non-obligation and human involvement. It is front-loaded and every word earns its place, with no filler or redundancy.

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

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

For a handoff tool, the description gives enough to understand its role, but it does not explain what the returned URL looks like, how the agent should present it, or what happens if the offer_key is invalid. With no output schema, the description should clarify the return value and usage flow; it leaves these gaps. However, the core purpose and safety are covered.

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 provides no explanation of any parameter. While parameter names like offer_key (with an enum) are somewhat self-explanatory, the description does not compensate for the lack of schema descriptions. The agent is left to infer the meaning and format of source, event_id, and event_title without guidance.

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

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

The description clearly states a specific verb ('Prepare') and resource ('review URL for a selected EventWave promotion package'), and explicitly distinguishes itself from checkout by stating it does not create checkout, invoice, charge, entitlement, or payment obligation. This differentiates it from the sibling prepare_event_promotion_checkout and makes the purpose unambiguous.

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

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

The description conveys that this tool is a precursor to checkout and requires human action, but it does not explicitly name the alternative tool (prepare_event_promotion_checkout) or state conditions for when to use this vs. that. The context is clear enough for an agent to infer usage, but an explicit exclusion would be stronger.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds 'Returns evidence state and original source URLs' and 'upcoming' to clarify the scope of results, which goes beyond the annotations. This is useful behavioral context without contradicting 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 concise sentence, front-loaded with the verb and resource, and includes return information and read-only status without fluff. Every element contributes to understanding the tool's core function.

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

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

With no output schema, the description mentions the return of evidence state and source URLs but does not explain how the filters interact, defaults, or pagination. For a tool with five optional parameters, more detail on usage semantics (e.g., whether filters are exclusive or additive) would improve completeness. However, the essential purpose is clear.

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 carries the burden for parameter understanding. It mentions city, category, date window (likely days_ahead), and keyword (query), but omits limit and does not explain how filters combine or the exact meaning of 'date window'. The schema provides enums and constraints, but the description does not add detail for limit or days_ahead beyond what the schema shows.

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

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

The description clearly states the action ('Search'), the resource ('upcoming EventWave public event records'), and the filtering dimensions (city, category, date window, keyword). It also mentions the return of evidence state and source URLs. This distinguishes it from sibling tools like get_eventwave_capabilities and promotion-related tools, which serve different purposes.

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 tool is for searching/finding events, which is distinct from the capability and promotion siblings. However, it does not explicitly state when not to use it or name alternatives. The context of sibling names is sufficient for a clear usage scenario, but a direct reference to alternatives would strengthen it.

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