Ecomwith Commerce Desk

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. Beyond that, the description adds real behavioral detail: values are trimmed, lowercased, and whitespace is replaced with underscores, and naming warnings are returned. The scope exclusions partially restate the annotations but are still useful specificity.

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 core action, then normalization behavior, then scope exclusions. No filler or redundancy; every clause carries information.

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

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

An output schema exists, so return structure needn't be explained, and annotations cover the safety profile. The description fills in the normalization and scope details that the low-coverage schema lacks, leaving only minor items (length bounds, warning format) to the structured 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 only 17% (just the url field), so the description has to carry the load, and it does: it names source, medium, campaign and the optional content and term, plus the normalization rules applied to those values. It doesn't mention the length limits, but transformation semantics are the more important gap and they are covered.

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 precise verb+resource: 'Format one HTTP(S) campaign URL with source, medium and campaign.' It also enumerates the optional fields, so an agent knows exactly what the tool produces. It doesn't explicitly contrast itself with the sibling calculators/reports, but the domain is distinct enough that confusion is unlikely.

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 (use this to assemble a UTM-tagged campaign link) but there is no explicit 'use when / don't use when' framing and no alternative tool is named. The closing negative clauses ('Never visits the URL, sends a message, saves a campaign or changes tracking settings') act as scope boundaries rather than 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 readOnly, idempotent, non-destructive, and closed-world behavior. The description goes well beyond that by disclosing the null-handling contract, the refusal to guess zeros or a default currency, the needs_input response with no estimate, and the scope limit that it does not read an ad account or change a budget. This is rich behavioral disclosure beyond structured fields.

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 is front-loaded and the critical input-handling rules follow in a logical order. However, there is some repetition: 'Ask for missing inputs even if asked not to ask questions' is restated by the needs_input sentence, and 'Unknown fields must be null, never guessed zeros' overlaps with 'Only explicit user-supplied zeros are valid.'

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 financial calculator with seven required parameters, an output schema, and full annotation coverage, the description covers the essential contract: what it computes, how unknown inputs are handled, the return state when inputs are missing, and its read-only scope. The output schema can carry return-value details, so no important agent-facing behavior is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter thoroughly, including units, null semantics, and the 3-means-3% rule. The description adds a general cross-parameter rule about nulls and explicit zeros, but nothing about individual parameter syntax or meaning that the schema does not already provide. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: calculate break-even and target-profit ROAS plus maximum CPA from user-supplied inputs. It is clear what the tool does, but it never distinguishes itself from the sibling compare_profit_scenarios or any other alternative, so sibling differentiation is absent.

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 strong conditional rules for missing inputs ('Ask for missing inputs even if asked not to ask questions', 'If any input is unknown, returns needs_input'), which is useful invocation context. However, it does not say when to choose this tool over siblings such as compare_profit_scenarios or when not to use it, leaving alternative selection implied at best.

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 mark it read-only, idempotent, non-destructive, and closed-world, but the description adds critical behavior: incomplete scenarios return needs_input with no numeric comparison, and complete scenarios return contribution, maximum CPA, and ROAS. It also enforces a strict null-vs-zero/default-currency rule for unknown inputs. This goes well beyond what annotations provide.

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

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

The description is four tight sentences with no filler. It front-loads the scope, then covers input rules, incomplete-scenario behavior, complete-scenario output, and exclusions. 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?

Given the nested input schema and existing output schema, the description covers the key scope, input constraints, and return behavior for incomplete versus complete scenarios. It does not explain return fields, which is acceptable because an output schema exists. The main gap is explicit routing away from sibling tools like calculate_break_even_roas.

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 description adds aggregate constraints such as two-to-five scenarios and one currency, plus a strong null handling rule. However, the schema already contains detailed field-level descriptions for the nested inputs, so the description mostly repeats or summarizes those semantics rather than adding new per-parameter meaning. This is adequate but not rich.

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: compare two to five pricing or cost scenarios in one currency. It also clarifies the outputs (contribution, maximum CPA, ROAS) and exclusions, so an agent can distinguish it from general marketing tools. It does not explicitly name a sibling alternative, which keeps it below a perfect score.

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 clear usage context: two to five scenarios, unknown inputs must be null, and incomplete scenarios must prompt labeled questions. It also states what the tool does not do, such as predict sales or change pricing or advertising. However, it does not name an alternative like calculate_break_even_roas, so the when-to-use routing is not fully explicit.

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, openWorld), so the description earns credit for adding real behavior: it rechecks publication state on every call, refuses withdrawn/unpublished/missing reports, withholds member content and private notes, and instructs the agent to retain publication/correction dates and verificationStatus labels without upgrading weaker evidence. It lacks only rate-limit or response-size guidance.

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 dense sentences, front-loaded with the action and slug provenance before constraints. Every clause carries information; the evidence-retention instruction is slightly secondary 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 annotations and an output schema already present, the description only needs to add selection and behavior context, which it largely does, including the withheld-content boundary. The untouched locale parameter and the exact return shape are the remaining minor 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 carry both parameters. It conveys the slug's origin and the language constraint indirectly ('unavailable-language report is not returned'), but never explains the locale enum values (en/zh) or how the slug credibly maps to a report. Partial compensation only.

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

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

States a specific verb (Read) and resource (guest excerpts and cited source links of a published/corrected Ecomwith weekly report), and explicitly distinguishes itself from list_public_weekly_reports by naming it as the source of the slug. An agent can tell exactly which report artifact this returns.

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?

Names the prerequisite explicitly ('using a slug returned by list_public_weekly_reports') and enumerates when-not conditions: withdrawn, unpublished, missing, or unavailable-language reports are not returned. Both the entry path and the failure conditions are stated rather than 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 declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the exclusion set (drafts, withdrawn, member-only, subscriber data, unpublished research) and the framing that these are dated editorial reports rather than a live news feed.

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: scope first, then the exclusion list, then the 'not a live news feed' clarification. No filler and every sentence carries distinct information.

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

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

An output schema exists, so return-value detail is unnecessary, and annotations cover safety. Between the scope cap and the exclusion list an agent has enough to call this correctly; only the locale parameter's semantics go 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%, so the description must carry parameter meaning. 'Up to ten' usefully conveys the ceiling behind the limit parameter's maximum of 10, but the locale parameter (en/zh) is never mentioned and no meaning is added for it; partial compensation earns a baseline 3.

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

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

States a specific verb (List) and resource (Ecomwith public/corrected ecommerce weekly reports), plus a hard scope cap of ten. The plural 'List' vs the sibling 'get_public_weekly_report' is inferable, but the description never explicitly contrasts the two, 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: it returns dated published/corrected reports, not a live feed, and excludes drafts, withdrawn issues, member-only sections and subscriber data. However there is no explicit when-to-use statement nor a pointed alternative (e.g. 'use get_public_weekly_report for a single issue'), leaving selection 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 readOnly, idempotent, non-destructive and openWorld. The description adds real value beyond them: the ten-result ceiling, the presence of content access labels, and specific data classes that are withheld (paid lesson bodies, drafts, customer data). It could still mention whether results are cached or paginated, hence 4.

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

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

Two sentences, no filler. The positive scope leads and the exclusions follow immediately, which is exactly the front-loaded ordering 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?

With an output schema present, return-value documentation is redundant, yet the description still summarizes it helpfully. Combined with the annotation coverage, an agent has enough to select and call it correctly; only query-formulation guidance 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 compensate. It partially does: 'English or Chinese' maps to the locale enum and 'up to ten' reflects the limit maximum. But nothing explains query syntax, length constraints or the limit default, so the schema still carries the bulk of the meaning.

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 precisely scopes the resource: Ecomwith published tutorial metadata, internal tool descriptions and public answer summaries. It also names the supported languages and the output shape (up to ten source links with content access labels), which the sibling tools (UTM builder, ROAS, profit scenarios, weekly reports) plainly are not.

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?

Explicit exclusions tell the agent when NOT to use it: the wider web, website fetching, paid lesson bodies, drafts and customer data. That is strong negative scoping. It stops short of naming a recommended alternative tool for those cases, so it is a 4 rather than a 5.

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