Commerce Intelligence

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

Annotations already declare this is a safe read-only operation. The description adds useful behavioral context by stating that results include severity and debiasing recommendations, and it discloses a concrete cost of 20 credits per call. It does not cover rate limits or authentication, but it goes beyond the annotations meaningfully.

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

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

The description is short and front-loads the core purpose, return contents, and cost. The fragment 'UNDERSTAND.' is slightly ambiguous, but overall the wording is efficient and does not waste space.

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

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

The output schema exists and annotations cover safety, so return details and behavioral safety are largely handled elsewhere. However, with 0% schema description coverage, the description should do more to explain 'goal' and 'session_id' and to clarify when this tool should be chosen over siblings.

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

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

Schema description coverage is 0%, so the description must explain the parameters, but it only implies that 'text' is the content to analyze. It gives no meaning for the optional 'goal' or 'session_id' parameters, leaving two of three parameters undocumented.

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: finding cognitive biases in messaging, UX copy, or product framing. This is clearly distinct from siblings like write_product_copy or find_hidden_barriers, so an agent can identify the tool's purpose 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 usage by naming the contexts where the tool applies: messaging, UX copy, and product framing. However, it does not explicitly say when to use this tool versus alternatives such as find_hidden_barriers or write_product_copy, leaving routing partly 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 this a safe, closed-world read (readOnlyHint true, destructiveHint false), so the safety profile is covered. The description adds genuinely useful information not in the annotations: it is a paid call at 20 credits / €0.20, which affects whether an agent should invoke it speculatively. Return format is not discussed, though an output schema exists; the stray 'CONVERT.' fragment adds no behavioral meaning.

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

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

The core value proposition is front-loaded and the input/cost details follow compactly; little waste. The single capitalized fragment 'CONVERT.' is unexplained noise that costs it a point.

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

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

Output schema presence removes the need to explain return values, and cost/input guidance covers the invocation essentials. For a paid, 3-parameter analysis tool the definition is serviceable but incomplete: session_id is undocumented and there is no statement of prerequisites, limitations, or how results tie to follow-up tools like fix_checkout.

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 compensate, and it partially does: it explains funnel_description (natural-language funnel steps) and funnel_data including the concrete JSON shape {steps: [{name, users}, ...]}, plus that it is optional. However, session_id is never mentioned, leaving one of three parameters unexplained in both the schema and the description.

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 where and why customers abandon the funnel, with statistically significant per-step drop-offs and the behavioral barrier at each point. That is far more concrete than a name restatement, but it never distinguishes itself from near-neighbors like find_hidden_barriers or predict_churn, which an agent could plausibly confuse with barrier detection.

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 'Input: describe the funnel steps, optionally with data' line tells the agent how to invoke it, which implies the usage context, but there is no explicit when-to-use / when-not guidance and no routing to the sibling tools listed. Adequate but leaves selection between diagnose_dropoff and find_hidden_barriers to inference.

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

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

Annotations already establish that this is a safe, read-only, non-destructive, closed-world operation. The description adds useful behavioral context by disclosing the exact cost: 20 credits / €0.20 per call. It does not describe return shape, but an output schema exists, so the remaining gap is minor.

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

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

The description is short and front-loads the core purpose before adding cost information. The standalone 'UNDERSTAND' tag is slightly opaque, but the overall structure is efficient and contains little waste.

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

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

The description covers purpose, contrast with self-reported barriers, and cost, and the output schema handles return values. However, for a tool with two required parameters and zero schema descriptions, omitting any explanation of behavior and population leaves the invocation critically under-specified.

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 the behavior, population, or session_id parameters. It gives no indication of what these required inputs should contain or how they shape the analysis. With three undocumented parameters, the description completely 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 states a specific diagnostic action: identifying hidden conversion barriers rather than self-reported reasons. It clarifies the kind of barriers (capability gaps, missing motivation, environmental friction), making the tool's purpose clear. It does not explicitly distinguish itself from sibling tools such as diagnose_dropoff or detect_biases, so it falls short of a 5.

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

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

The description offers only an implied usage context via 'UNDERSTAND' and the contrast with 'what they say.' It does not state when to use this tool versus alternatives like diagnose_dropoff, detect_biases, or predict_churn. An agent must infer the routing decision.

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, destructiveHint false and closed-world, so safety is covered. The description adds real context beyond them: it discloses the return shape ('step-by-step redesigned flow with friction removed and behavioral principles applied') and the cost ('20 credits (€0.20 per call)'), which an agent needs for budget decisions. It does not say whether the call fails on sparse input or how long a redesign takes, so it is not exhaustive.

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

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

Three short lines, front-loaded with the outcome and followed by return and cost details; nothing is padded. The bare 'CONVERT.' token is cryptic in isolation but is still one word spent for a category signal.

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 elaboration, and the annotations plus the explicit credit cost give an agent the operational picture. The missing piece is any guidance on the required 'current_flow' input, which is essential to calling the tool correctly and is absent from both schema and description.

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 two parameters, so the description carries the full burden and fails: 'current_flow' (required) is never explained in terms of expected format or granularity, and 'session_id' is not mentioned at all. An agent must guess what to pass.

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 ('Redesign a checkout, signup, or purchase flow') plus the goal ('reduce abandonment'), which is clear enough to separate it from diagnose_dropoff or optimize_onboarding. It stops short of naming the sibling it supersedes, so an agent still has to infer the boundary from the flow-redesign framing alone.

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 purpose implies when to reach for it (an existing flow that leaks conversions), but there is no explicit when-not clause, no prerequisites, and no mention of alternatives such as diagnose_dropoff for diagnosis versus this tool for redesign. Usage is only implied.

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

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

Annotations already declare readOnly=true, destructive=false, openWorld=false, so the safety profile is covered. The description does add genuinely useful context not in structured data — a per-call cost of 20 credits (€0.20) — but 'RETAIN' is unexplained jargon and it says nothing about what the design output looks like or whether the original flow is touched.

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 lead with the outcome, then the mechanism, with no filler. The trailing 'RETAIN. 20 credits' fragment is cryptically worded but at least puts cost up front where it can be seen before invoking.

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

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

An output schema exists, so return values need not be explained, and annotations cover safety. However for a tool whose only required input is a free-form string, giving zero indication of expected content or shape is a material gap an agent cannot resolve on its own.

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 and it does not. The required `current_flow` could be prose, a step list, a URL, or JSON, and `session_id` (default empty) is never mentioned at all — an agent has no basis for formatting either argument.

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 concrete outcome (reduce time-to-value) and the two actions it performs: identify onboarding friction and design a faster path to the 'aha moment'. This is a clear verb+resource statement, but it never distinguishes itself from closely-related siblings like find_hidden_barriers or diagnose_dropoff, which could plausibly also surface onboarding friction.

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 reach for this tool versus the seven siblings, several of which overlap conceptually (find_hidden_barriers, diagnose_dropoff, fix_checkout). 'RETAIN' appears without explanation and gives no usable selection guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely useful cost context (20 credits / €0.20 per call), which is not in structured data, but says nothing about analysis depth, latency, or what the credit spend buys.

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 content sentences plus a cost line, front-loaded with the capability and its components. The standalone 'CONVERT.' token is cryptic and slightly disrupts flow, but overall there is little waste.

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

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

An output schema exists, so return-value explanation is not required, and the credit cost is disclosed. However, for a 3-parameter tool with zero schema descriptions, the definition should still say what to supply for the required product and the optional context/session fields.

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, and the description says nothing about what 'product', 'context', or 'session_id' should contain. It does not compensate for the coverage gap at all, leaving the agent to guess at the required input 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 concrete deliverables — price framing, anchoring, tier structure, decoy pricing, value articulation — with a clear verb (design) and outcome (maximize willingness to pay). None of the siblings (churn, onboarding, checkout, copy) overlap, so an agent can route unambiguously.

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

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

There is no guidance on when to use this versus alternatives, no prerequisites, and no exclusions. The bare tag 'CONVERT.' hints at a funnel stage but does not tell the agent what inputs or situation qualify for a pricing optimization request.

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 operation with destructiveHint=false and openWorldHint=false. The description adds useful context by stating the return content and the per-call cost of 20 credits, but it does not mention authentication, rate limits, or data freshness. With annotations covering the safety profile, this is adequate but not rich.

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

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

The description is short and front-loaded, with purpose first and return/cost details after. "RETAIN." is an unexplained fragment that slightly reduces clarity. Overall it is efficient and free of redundant text.

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

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

An output schema exists, so the description need not fully document return values, though it still summarizes them. For a three-parameter tool with zero schema description coverage, the definition should say more about how to supply user_behavior and what context/session_id are for. It covers safety indirectly through annotations and mentions cost, but input expectations remain unclear.

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 input schema provides only parameter names and titles. The description does not explain user_behavior, context, or session_id, nor does it indicate expected formats. The churn-prediction purpose somewhat implies what user_behavior might mean, but no parameter-specific guidance is provided.

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: identify customers about to leave and explain why. It also summarizes the output as churn risk scores with behavioral drivers and retention interventions. It does not explicitly differentiate this from sibling tools such as diagnose_dropoff, so it falls short of a 5.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives. "RETAIN" appears to be a category label but does not explain usage conditions, prerequisites, or exclusions. An agent can infer it is for churn prediction, but must guess the appropriate 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 a safe, read-only, non-destructive, closed-world operation, so the bar is lower. The description usefully adds cost information ('20 credits, €0.20 per call') and discloses the persuasion techniques used, but says nothing about how the draft is transformed or what constraints apply to the output.

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

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

The core sentence is front-loaded and efficient, but 'CONVERT.' is pure marketing noise that occupies a line without informing an agent, and the persuasive-technique list is only marginally useful relative to the missing parameter context.

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, but with four undocumented parameters, no usage guidance, and no statement of how inputs shape the generated copy, the definition leaves an agent guessing on the parts that matter 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% across four parameters, and the description supplies no compensating meaning for any of them. It never explains what 'draft' is (source text? prior version?), what 'goal' should contain, or what 'audience' and 'session_id' do.

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

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

The description names a specific verb and resource set — product descriptions, landing-page copy, marketing messages — so an agent can immediately tell it is a copy-generation tool, clearly distinct from the analytics-oriented siblings (predict_churn, optimize_pricing, fix_checkout). It stops short of explicitly differentiating itself from those siblings, which is why it is not 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?

Use is only implied by the enumerated artifact types ('product descriptions, landing page copy, or marketing messages'), with no guidance on when to reach for this tool rather than a sibling, no prerequisites, and no stated exclusions. An agent must infer the triggering context.

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