Versium REACH

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

With readOnlyHint and destructiveHint=false already covering safety, the description adds substantial behavioral context: unconnected platforms are returned as connected:false, connecting only happens in the REACH web app, expired lists cannot be exported, each platform has a minimum record count, and only lists with Online Audience output are eligible. These are business rules not present in annotations or schema.

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

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

The description is front-loaded with purpose and then organized into parameter-driven use cases and eligibility constraints. Every sentence is informative, though the middle paragraph is dense and could be slightly tighter for readability.

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

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

Given an output schema exists, return-value details are not required in the description. The description nevertheless covers eligibility rules, connection handling, and the relationship to export_list_to_ads, making it complete for an agent to call and interpret this read-only discovery tool correctly.

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

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

Schema coverage is 100%, so parameters are already well documented. The description still adds cross-tool semantics: platform+account_id yields Ad Platform Audiences that export_list_to_ads can consume via audience_id, and list_id produces per-platform eligibility with failure reasons. This meaningfully exceeds the schema alone.

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 ('Discover where a list can go in an Ad Platform Export') and enumerates exactly what is returned: supported platforms, connection status, ad accounts, existing audiences, and per-list export eligibility. This clearly distinguishes it from the sibling export_list_to_ads, which performs the actual export, and from ads_export_status.

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 explicitly states the conditional calls: pass platform and account_id to retrieve that account's existing Ad Platform Audiences, and pass list_id to check exportability with reasons. It also explains what to do when a platform is unconnected (direct the user to the REACH web app Integrations page), leaving no ambiguity about when and how to use this tool versus export_list_to_ads.

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 useful lifecycle context: `status` moves from queued to uploading to success or failed, and it explains the success and failure result fields. It does not mention polling cadence or auth requirements, but those are not critical given the annotations and output schema.

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

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

The description is two tightly written sentences. It front-loads the action and provides the status lifecycle and result interpretation without unnecessary 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?

Given the simple two-parameter schema, rich annotations, and an output schema, the description covers the essential operational context: what is being checked, the status progression, and what success/failure returns mean. Nothing an agent needs in order to invoke it correctly is missing.

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

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

`history_id` is clarified as coming from `export_list_to_ads`, which is useful beyond the schema's own parameter description. However, `platform` is only covered by the enum in the schema, and the description does not explain its semantics or how platform affects the check.

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: checking an Ad Platform Export by `history_id`. It explicitly ties the tool to `export_list_to_ads`, which distinguishes it from sibling tools such as `ads_export_options` and `job_status`.

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 clearly says to use this tool for an export started with `export_list_to_ads`, giving the prerequisite context. It does not explicitly discuss when to prefer alternatives such as `job_status`, so it falls short of full alternative routing guidance.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral context beyond annotations: it explains the enrichment process, the role of required_outputs in filtering results, and the configurable maximum outputs (cfg_max_emails_b2c, cfg_max_phones_b2c). It does not contradict annotations and adds useful operational details, though it doesn't cover every edge case (e.g., error handling 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 well-structured with a clear purpose statement, usage guidance, and a bulleted 'Tips for Best Results' section. It is slightly longer than necessary but every sentence adds value, and the tips are practical. The front-loading of the core purpose and usage condition is effective.

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 that an output schema exists (per context signals), the description does not need to explain return values. It covers input options, output selection, configuration parameters, and the matching strategy. The description is complete enough for an agent to know how to invoke the tool correctly, including the US-only limitation (noted in the schema) and the required outputs behavior.

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

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

Schema coverage is 100% and every parameter has a description. The description adds significant semantic value by explaining the two primary input modes (LinkedIn URL vs. name+city/state) and the purpose of required_outputs, which is not fully apparent from the schema alone. It also clarifies the relationship between outputs and required_outputs, making parameter usage unambiguous.

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: enriching a business contact with consumer-side profile data, specifying the resource (business contact) and the action (append consumer data). It also names the target use case (B2B2C) and the data types involved, making it distinct from the sibling tools like c2b_append or contact_append.

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 explicitly states when to use the tool ('when users ask for B2B2C...') and provides best-practice tips for input formats (LinkedIn URL vs. name+city/state). However, it does not mention when not to use it or name alternative tools, which would earn a 5. The usage context is clear but lacks explicit exclusion criteria.

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 idempotentHint=true, and the description adds valuable context by framing the operation as an estimate of audience sizes rather than a list build. It also discloses the cfg_b2cloc behavior for switching between business-location and home-location targeting, which is useful beyond the schema.

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

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

The description is front-loaded with a clear purpose sentence and then organized into concise, scannable bullet tips. Each tip earns its place by providing actionable guidance for a complex 14-parameter tool, with no redundant filler.

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

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

Given the tool's complexity, the description is complete: it states the core purpose, offers filter selection strategies, points to the options tool for valid values, and clarifies location targeting behavior. The output schema and annotations cover return values and safety, so the description does not need to repeat those.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful parameter guidance: it explains when to use title_seniority vs department, when to provide SIC codes, and how to interpret cfg_b2cloc. These tips go beyond the schema definitions by linking parameters to targeting strategies.

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 and resource: 'Estimate business contact audience sizes with firmographic and role-based targeting using Versium's B2B Persona Audience Builder (B2B Listgen) API.' This clearly distinguishes the tool from siblings like b2c_listgen_estimate (B2C) and b2b_listgen_options (options lookup).

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 'Tips for Best Results' section provides concrete guidance on when to use specific filters, such as using title_seniority for leadership focus, department for functional targeting, and SIC codes for strict industry alignment. It also explicitly directs users to call the B2B Persona Listgen Options tool for high-cardinality field values, though it does not explicitly contrast with the B2C sibling tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about high-cardinality fields but doesn't disclose pagination behavior or response format beyond what the schema implies. With annotations covering the safety aspects, a 3 is appropriate.

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

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

The description is two sentences, front-loaded with the purpose, and every word earns its place. The first sentence states what it does, the second explains when to use it. No fluff.

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

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

The tool has an output schema, so return values are documented. The description covers purpose and usage context. With 100% schema coverage and good annotations, the description is complete enough for an agent to select and invoke the tool correctly. The only minor gap is not listing example field values, but that's not necessary.

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 all four parameters are documented in the schema. The description adds the context that fields like NAICS are high-cardinality, which helps understand why the tool exists, but doesn't add parameter-specific meaning beyond the schema. Baseline 3 is correct.

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

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

The description clearly states the tool returns allowed option values for B2B Persona Listgen filter fields, naming specific examples (NAICS, department, role). It distinguishes itself from the sibling b2c_listgen_options by specifying B2B, and the verb 'Return' is specific to the resource.

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

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

The description explicitly says 'Use this tool when you need the valid values for large, high-cardinality fields too big to embed directly in tool schemas,' which provides clear context for when to use it. It doesn't explicitly mention alternatives or when not to use it, but the context is sufficient given the sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which matches an 'estimate' operation, and the description adds non-obvious model semantics: the enum ["Y"] flag convention with a concrete Washington/golf/pets example. It does not disclose cost/credit consumption, whether estimates create a persistent job, or rate limits — meaningful context for a 95-parameter sizing call that the annotations do not cover.

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

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

The purpose is front-loaded in sentence one, followed by scoped operational notes and a short tips block, with no filler. Minor inefficiency: the options tool is referred to both as 'Consumer Audience Options tool' and `b2c_listgen_options`, and the 'Tips' bullets are somewhat generic.

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 correctly omitted, and the description handles enum-flag semantics well. But for a 95-parameter, zero-required tool it never states what a minimal valid call looks like or which of required_fields/optional_fields/max_coverage must be coordinated — the coordination rule lives only in the schema's required_fields text, not in the 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?

With 95 parameters including 54 enums and only 57% schema description coverage, the description carries real weight by explaining the shared `enum: ["Y"]` activation convention and routing ambiguous code sets (income, net worth, home value, occupation, attribute_flags) to the options tool. That single convention covers a large share of the otherwise undescribed boolean-style flags, though no guidance is given on safe defaults or minimal viable filter sets.

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 first sentence gives a specific verb (estimate) and resource (consumer audience sizes) and names the backing API (Versium Consumer Audience Builder / B2C Listgen), so the agent knows this is a sizing/estimate call over demographic filters. It implicitly separates from b2b_listgen_estimate via 'consumer,' but never names that sibling or explains the consumer-vs-business split 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?

It gives real procedural guidance — look up high-cardinality values (e.g., esthhldincome) via the options tool, call b2c_listgen_options with field: "attribute_flags" for flag meanings, and a 'Tips' list recommending incremental filter building. However, these are all intra-tool/parameter hints; there is no guidance on when to use this estimate versus sibling tools like preview_list, setup_list, or b2b_listgen_estimate, and no stated exclusions.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context about high-cardinality fields and why the options cannot be embedded in schemas. No contradictions exist between the description and 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 two sentences long, front-loaded with the core purpose, and contains no filler or redundant material. Every sentence contributes meaning.

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 a simple read-only options lookup with full schema coverage, rich annotation coverage, and an output schema. The description explains both the core function and appropriate use, making it complete for an agent to understand and invoke the tool correctly.

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

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

All 4 parameters already have complete descriptions in the input schema, so the description does not need to repeat parameter details. However, it also adds little beyond the schema; for example, it does not clarify which fields are valid or that `field` is semantically required despite the schema listing no required parameters.

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 and resource: 'Return allowed option values for Consumer Audience Builder (B2C Listgen) fields.' It clearly identifies the consumer/B2C scope, distinguishing it from the sibling b2b_listgen_options tool.

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

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

The description explicitly states when to use the tool: 'Use this tool when you need the valid values for large, high-cardinality fields too big to embed directly in tool schemas.' It provides a clear context but does not explicitly mention alternatives or when not to use it, such as pointing to the B2B sibling tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context about matching logic (LinkedIn URL or name+contact) and output fields, which clarifies what the tool returns. No contradiction with annotations exists; the words 'enrich' and 'appends' could be ambiguous, but annotations resolve that it is a read-only enrichment.

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 moderately detailed but well-structured: the main purpose is front-loaded, followed by the usage trigger and bulleted tips. Each section contributes relevant guidance; there is little fluff, though the LinkedIn URL format tip somewhat repeats the schema. Overall it is efficiently organized.

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

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

Given the tool's complexity (11 parameters, a complex anyOf requirement, and an output schema), the description covers the critical matching conditions and best practices well. It does not discuss error scenarios or rate limits, but the annotations and output schema handle safety and return structure. For this complexity, the description is sufficiently 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?

With 100% schema description coverage, baseline is 3. The description adds significant value beyond the schema by explaining the acceptable matching combinations (anyOf: LinkedIn URL, or first/last plus email/phone/city+state) in plain language. It also clarifies the use of rcfg_require_email and rcfg_require_value with practical examples, which helps an agent select parameters correctly.

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 function: enrich consumer marketing records with business demographics for B2B segmentation. It lists specific appended fields (job title, seniority, department, business email, LinkedIn profile) and distinguishes itself from siblings through the explicit C2B (Consumer to Business) focus. The name and title align with this purpose.

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 an explicit trigger: 'Use this tool when users ask for C2B, c2b, or Consumer to Business Person data.' It also includes practical best-practice tips (e.g., provide full name and email for best match quality). However, it does not name sibling alternatives or explicitly state when not to use this tool, so it lacks exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered and there is no contradiction. The description adds operational context around match quality and output cardinality, but it does not describe the actual lookup/return behavior or any additional side-effect considerations beyond what annotations already provide.

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

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

The purpose is stated in one front-loaded sentence, followed by four scannable bullet-point tips. There is no fluff, repetition, or redundant restating of the schema. Every sentence contributes actionable information, and the format is easy for an agent to parse.

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

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

The schema is 100% covered and an output schema exists, so many invocation details are already structured. The description adds useful operational tips, but given 20 siblings including several other append tools, it should explicitly state when contact_append is the right choice versus b2b2c, c2b, demographic, or firmographic append. It also omits the US-only scope that is visible in the 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?

All 15 parameters have rich schema descriptions, so the baseline is 3. The description adds meaningful usage semantics by explaining when to use indiv, how output type selection affects match quality, and when to raise cfg_maxrecs. This goes beyond the schema's structural descriptions without needing to compensate for any 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 starts with a specific verb ('Enrich') and a clear resource ('marketing contact records'), and names the output types (mailing address, email, phone). It is unmistakable what the tool does, but it does not explicitly contrast contact_append with the many sibling append tools, so it misses the top 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?

The 'Tips for Best Results' provide practical guidance on parameter usage: use indiv for a specific person, request one output type per call for phone match quality, and set cfg_maxrecs for multiple acceptable records. However, there is no guidance on when to choose this tool over sibling append tools like b2b2c_append or c2b_append, nor any when-not-to-use conditions.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent operation. The description adds important behavioral context beyond annotations: setup prerequisites and charge-on-finish consent requirements, including the `consent_required_job_types` meta field.

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 in the first sentence, followed by actionable prerequisites and consent guidance. The description is appropriately sized with little waste, though it could trim minor 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?

Given the rich input schema, output schema, and annotations, the description covers the key workflow details an agent needs: listgen vs enrichment, setup_list prerequisite, project selection preference, and consent handling. Remaining details such as job polling are covered by output schema and sibling tools.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds workflow meaning beyond the schema: use `project_id` when possible, run `setup_list` before enrichment, and only set consent after user approval. It also references the `consent_required_job_types` meta field.

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: "Create a listgen job, or a batch enrichment job over one of the user's lists." It is clear enough to distinguish creation from inspection/status siblings, but it does not explicitly name alternatives such as the estimate or job_status tools.

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

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

It gives concrete prerequisites: run `setup_list` first for enrichment, prefer `project_id` when possible, and obtain consent before setting `usage_consent_confirmed = true`. It does not explicitly state when not to use this tool or 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?

Annotations already indicate non-read-only and non-destructive behavior, lowering the burden. The description adds the auth context ('for the authenticated user') but does not disclose other behaviors like name uniqueness or error handling. 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 two sentences, front-loaded with the primary action, and every word serves a purpose. No fluff or 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 simple one-parameter tool with an output schema present, the description covers purpose, usage trigger, and authentication context. There is no need to describe return values because the output schema exists.

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

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

The schema already provides 100% coverage of the single parameter ('Project name'). The description does not add significant additional meaning beyond calling it a 'project container,' so it stays at the baseline of 3.

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

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

The description clearly states the specific action ('Create a new REACH project') and resource ('project'), and the addition of 'for the authenticated user' clarifies scope. It distinguishes itself from siblings like list_projects and show_project by being the create 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 description gives an explicit usage trigger: 'Use this tool when a user asks to create a project container before working with lists.' This provides clear context, though it does not explicitly mention alternatives or 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 and closed-world, so the safety profile is covered. The description adds genuinely non-structured behavior: that match confidence rises with more identifiers, and that cfg_required/rcfg_require_value can suppress records, which affects what the agent gets back. It does not say what happens on a no-match record.

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?

Purpose is front-loaded in the first sentence, with configuration tips scoped under a clear heading. Content is well sized for a 14-parameter tool; only minor overhead from leading whitespace and the redundant title restatement.

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 needn't document return values, and annotations cover safety. It covers purpose, matching strategy, and result filtering adequately; the notable remaining gap is behavior on unmatched records and any cost/credit implications of an enrichment call.

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

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

Schema description coverage is 100%, so the baseline is 3. The tips go beyond field definitions by advising which parameters to combine for higher match confidence and by explaining the practical role of cfg_required and rcfg_require_value as response filters, adding strategy the schema does not convey.

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 ('Append consumer marketing records') plus the data domain (household and lifestyle insights) and the intended use case (audience segmentation). This implicitly differentiates it from b2b or firmographic append siblings, but never names them 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 tips give input-strategy guidance (request only needed categories, combine identifiers, enforce required fields), which tells the agent how to call it well. However, there is no explicit statement of when to prefer this tool over contact_append, b2c_listgen_*, or the B2B append siblings, so tool selection is left to inference from the name.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not restate safety traits. The description adds useful contextual scope about searching official docs and defaulting to both doc sources. However, it does not add deeper behavioral detail such as response shape, pagination, or source behavior beyond the schema.

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

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

The description is concise and well-structured: a clear purpose sentence, a usage context sentence, and three bullet usage tips. Every line adds practical value without irrelevant 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?

With an output schema, fully detailed annotations, and only one required parameter, the description does enough by stating the search domain and when to use the tool. It could be slightly more complete with explicit mention that search is read-only, but the annotations already provide that context.

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

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

The input schema has 100% parameter coverage with descriptions and defaults. The description adds extra semantic value by explaining the meaning of 'app' vs 'api' docs_target choices in practical terms. This goes beyond the schema's basic enum documentation.

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 identifies the tool's function: searching Versium's official documentation for web application or API information. This is specific and aligned with the tool name, and it is clearly distinct from all sibling tools, which handle data append, job, project, and list operations rather than documentation search.

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 explicitly states when to use the tool: 'Use this tool when a user has questions about how to use the Versium REACH platform.' It also provides concrete guidance for choosing docs_target values. It does not explicitly discuss alternatives or when not to use the tool, but the sibling context makes alternative use cases obvious.

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?

No annotations are provided, so the description carries the full burden. It reveals that the tool returns validation status and whether the email is valid for mailing, and explains the optional alternate-email behavior. However, it doesn't disclose error handling, rate limits, or any side effects, but for a read-only validation tool this is acceptable. It adds moderate value beyond the schema.

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

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

The description is concise with a clear main line and a bulleted list of tips. It is front-loaded with the primary purpose guide. Each tip is relevant and adds value. Slightly long but well-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?

With 12 parameters and an output schema, the description covers enough context: it explains the core behavior, optional alternate email feature, and tips for better results. It doesn't delve into output format, but the output schema likely covers that. For a tool with this complexity, the description is adequate and 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?

The schema covers the parameters well (100% have descriptions), so the baseline is 3. The description adds value by clarifying the purpose of additional contact info ('improve alternate email matching') and explains how rcfg_exclude_domains works. This goes beyond schema descriptions, justifying a slightly higher score.

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: 'Validate email addresses and optionally get alternate valid emails using Versium's Email Validation API.' It specifies the verb (validate), the resource (email addresses), and the API used aids in distinguishing it from sibling tools like data append tools.

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

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

The description includes 'Tips for Best Results' which provides practical usage guidance, such as using hashed emails, including additional contact info for better alternates, and filtering domains. While it doesn't explicitly state when not to use the tool or compare to alternatives, the context is clear enough for tool selection among the 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?

Adds substantial context beyond annotations: 'Not billed', background/async execution, and the single-concurrent-export rule with the already_in_progress response including the possibility that the running export's account/audience differ from the request. These are non-obvious behavioral traits that annotations (destructive/not-idempotent) do not convey.

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

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

Front-loads the core action, then prerequisites, then the async/concurrency caveat. Well organized and largely waste-free, though the three-paragraph split is slightly longer than strictly necessary.

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 destructive, non-idempotent mutation tool with an output schema already covering returns, the description still supplies everything an agent needs: prerequisites, async follow-up via history_id, and the concurrency edge case. Complete against the available structured data.

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 60%; the description compensates by explaining where account_id/audience_id come from (ads_export_options) and the mutually exclusive audience_id vs audience_name semantics. list_id and platform rely on the enum and general context, but the description's mapping of audience_name to 'create new' adds real meaning beyond the schema.

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

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

States a specific verb (start/push) and resource (Ad Platform Export / Online Audience to ad account), and clearly distinguishes itself from siblings ads_export_options, ads_export_status, and the append tools. An agent can identify the exact action 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?

Explicitly says how to find platform/account_id/audience_id via ads_export_options, when to use audience_name vs audience_id (create new vs add existing, not both), and to check progress with ads_export_status. Also documents the concurrent-export exclusion. Nothing left to inference.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description is not expected to restate those. The description adds context about typical use cases (account targeting/segmentation) and tips that imply behavior (e.g., domain yields fastest results). However, it does not disclose potential limitations, such as behavior with incomplete inputs or whether results may vary. The bar is lower due to annotations, but the description adds only modest behavioral context beyond them.

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

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

The description is compact and front-loaded with the core purpose, followed by a clearly separated 'Tips for Best Results' section. Each sentence is purposeful and provides actionable guidance. The structure is easy to scan, and there is no redundant filler, though the tips could be seen as slightly verbose for some users.

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

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

The tool has 10 optional parameters and an output schema exists. The description explains the overall function, provides strategic tips on parameter selection, and mentions filtering via rcfg_require_value. It does not elaborate on return formats (handled by output schema) or edge cases, but for a read-only enrichment tool with high schema coverage and annotations, the context is sufficiently complete for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so all parameters are described in the schema. The description adds value by linking certain parameters to usage tips: domain for speed, address/phone for business name searches, and rcfg_require_value for filtering. This goes beyond the schema's basic field descriptions and helps the agent understand parameter interactions, though it doesn't cover every combination.

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 enrich business records with firmographic data such as company details, location, industry, employee counts, and revenue. The verb 'enrich' and resource 'business records' are specific, and the listed fields distinguish it from other append tools. However, it does not explicitly differentiate itself from sibling tools like b2b2c_append, though the term 'firmographic' inherently signals the data type.

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 actionable tips on how to get best results (e.g., provide domain for fastest results, include address/phone for business name searches, use rcfg_require_value for filtering). These are usage instructions but not guidance on when to choose this tool over alternatives like b2b2c_append or contact_append. There is no explicit 'when to use' or 'when not to use' statement, 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 declare openWorld=true, non-idempotent, non-destructive, so the safety profile is covered. The description adds real behavior the annotations cannot: it requires a pre-connected Google/OneDrive account, specifies which file types are supported per provider, and discloses that rows beyond the upload limit are silently dropped with record_count reflecting only what was kept. That truncation warning is the highest-value disclosure here; only error/re-import behavior is left unstated.

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?

Front-loaded purpose, then prerequisite, then the exact call chain, then supported types, then the truncation caveat. Every sentence carries operational information and none repeats the schema or annotations.

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 7-parameter, open-world, non-idempotent import with an output schema, the description covers purpose, prerequisites, next calls, supported formats, and the data-loss caveat. What remains (e.g., empty/error file behavior, sheet_name requirement for multi-tab files) is already handled by the 100%-covered schema, so the gaps are minor.

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

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

Schema coverage is 100%, so the schema already explains url, file_id, provider, and sheet_name. The description adds a condition the schema does not spell out: drive_id is needed specifically for OneDrive files outside the user's own drive, and it frames url versus provider+file_id as mutually exclusive paths. That is genuine added meaning over the field descriptions.

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 ('Import a Google Drive or OneDrive file into REACH as a new list') and immediately scopes who performs it ('using the account the user connected'). The workflow sentences make it unmistakable against siblings like setup_list and create_job, which are named as the next steps rather than 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?

Explicitly tells the agent how to get here ('REACH doesn't browse drives: find the file with a Google Drive or OneDrive/Microsoft 365 MCP server'), what to pass, and what to call afterwards ('setup_list with the returned list_id, then create_job'). This is a full usage contract, not an implied one.

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 read-only, idempotent, non-destructive behavior. The description adds the output cardinality limit ('up to 3 associated business domains') and the range of returned firmographic attributes, which is useful beyond the annotations. It does not discuss edge cases like invalid IPs, but the schema pattern covers input format.

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 a clear one-sentence summary followed by a short tips section. The last bullet and IP-validity tip are somewhat redundant with earlier content, but the overall length is reasonable and scannable.

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

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

For a simple 2-parameter lookup with a single required field, an output schema, and strong annotations, the description covers purpose, expected output, and practical use. It could be more complete by naming sibling alternatives or clearly scoping when not to use it, but nothing critical is missing.

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

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

Schema description coverage is 100% and both parameters (ip and rcfg_max_time) already have meaningful descriptions. The tool description adds no parameter-level detail beyond the schema, matching the baseline for high schema coverage.

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

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

The description uses a specific verb ('Discover') and resource ('business domains and firmographic information from IP addresses'), clearly distinguishing this from sibling append/list tools by the IP-to-domain lookup mechanism. It states the core action and result (up to 3 domains with firmographic details).

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 'Tips for Best Results' section gives clear use context: use for identifying businesses from web traffic or server information. It does not explicitly name alternatives or when-not-to-use scenarios, so it falls just short of 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 readOnlyHint, idempotentHint, and destructiveHint=false, establishing it as a safe, non-mutating read. The description adds value by specifying what status includes (progress, ETA, output list readiness) and clarifies it works for both running and finished jobs. This complements rather than repeats 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?

Two sentences, both purposeful. The first identifies the action and the prerequisite (after create_job), the second specifies use cases. No wasted words, and the core purpose 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?

The tool is simple (one parameter) and has an output schema, so return value details are unnecessary. The description states what status information is available and when to poll. It doesn't mention error handling (e.g., invalid job ID), but that's minor given the schema and annotations.

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

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

The schema covers the single parameter (job_id) with a description ('Positive integer job ID (must be ≥ 1)') at 100% coverage. The description adds no extra parameter meaning beyond the tool's purpose, so the baseline 3 applies.

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

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

The description clearly states the tool checks the status of an existing job, specifically after create_job. It lists the concrete outputs (progress, ETA, output list readiness) and distinguishes it from creation and list-management siblings by focusing on polling existing jobs.

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 explicitly says to use it for polling progress, ETA, and output list readiness while a job is running or after it finishes. It doesn't mention when not to use it or name alternatives, but the context 'after create_job' implicitly excludes creation and other operations. Given the sibling list has no other status tool, this is adequate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds that it returns lists for the authenticated user and supports optional filtering, but does not disclose pagination behavior, ordering, or what happens when no filters are provided. With annotations covering safety, a 3 is appropriate.

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

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

The description is two short sentences, front-loaded with the main action and resource. The second sentence adds filter options concisely. No wasted words, though it could have been slightly more informative about behavior.

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

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

For a read-only list tool with a full output schema and 100% parameter schema coverage, the description is adequate. It covers the core purpose and optional filters. It doesn't mention pagination or default behavior, but the output schema and annotations fill in much of the context. Slightly more detail on result ordering or default scope would push it higher.

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 all three parameters (limit, search, project_id) are already documented in the schema. The description mentions 'filter by project or name prefix' which maps to project_id and search, adding slight context but not much beyond the schema. Baseline 3 is correct.

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

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

The description states a specific verb ('List') and resource ('REACH lists') and notes it is for the authenticated user. It distinguishes itself from siblings like show_list and preview_list by indicating it lists multiple lists, though it doesn't explicitly name alternatives. The title is redundant but the description adds clarity.

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 context: listing lists for the authenticated user, with optional filters. It does not explicitly state when to use this tool versus alternatives like show_list or preview_list, nor does it mention exclusions. The optional filters give some context but no direct comparison to siblings.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds limited behavioral context beyond the annotations, such as the 'REACH' qualifier and the fact that it's for the authenticated user, but it doesn't elaborate on pagination, rate limits, or other behaviors. It's not contradictory and adequately supports 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 remarkably concise, consisting of just two sentences. The first states the core action, and the second offers actionable guidance. No unnecessary words, perfectly front-loaded 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?

For a simple read-only tool with two well-documented optional parameters, an output schema, and rich annotations, the description is complete. It explains the tool's purpose and provides a usage hint, covering all necessary aspects for an agent to use it correctly.

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

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

The input schema provides complete descriptions for both parameters ('Maximum number of returned projects' and 'Optional prefix search on project name'), giving 100% schema coverage. The description adds no additional parameter-level detail, which is acceptable as the schema already does the heavy lifting.

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

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

The description clearly states the verb ('List'), the resource ('REACH projects'), and the scope ('for the authenticated user'). It also differentiates from siblings by indicating its role in preparation for `show_project`, making its 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 provides a clear use case: 'Use this tool to find the right project before calling show_project.' This gives contextual guidance for when to use it, though it does not explicitly exclude alternatives or mention contrast with other list-type tools (e.g., list_lists), keeping it from a perfect score.

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=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral nuance beyond the annotations, including that the count parameter is only a hint, the actual row count may differ by list type and backend behavior, and a service default applies when omitted. This is helpful and consistent with the annotations.

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

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

The description is concise and front-loaded with the primary purpose. It covers sample behavior, count variability, and default behavior in four short sentences. There is slight redundancy between 'Preview a sample of rows' and 'Returns a row sample', but no substantial 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?

For a simple two-parameter read-only preview tool with full schema coverage and an output schema, the description context is appropriately complete. It explains the extent of the sample, the count limitations, and backend variability. It does not address all possible sibling distinctions, but that is not essential for using this tool correctly.

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

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

The schema already has 100% coverage for both list_id and count, including the hint-like nature of count. The description mostly paraphrases what the schema already states, reinforcing that count is a hint and varies, but it does not add additional meaning beyond the structured schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool 'Preview a sample of rows from a REACH list' and further clarifies that it inspects the actual data rows. This specific verb-resource combination differentiates it from siblings like show_list, which likely shows list metadata or structure rather than row samples.

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 concise use case: 'Use this tool to inspect the actual data rows in a list.' This provides clear context for when the tool is appropriate. It does not explicitly mention when not to use it or name alternatives, but the usage context is sufficient for a read-only preview tool.

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

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

Annotations declare destructiveHint=true, and the description adds the crucial nuance that the call without `header_map` changes nothing — a dry-run mode the annotations alone would obscure. It also notes that `create_job` re-validates size, export status, and account access, so this tool isn't the last gate. It stops short of explaining what an applied mapping overwrites on the underlying list.

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?

Opens with a single-sentence purpose, then numbers the workflow steps so the two-phase call pattern is front-loaded. The closing paragraph on which lists accept a new mapping is dense but every sentence informs the call decision.

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 correctly avoids documenting return values and instead explains how to use the response fields it references. For a stateful, dry-run-then-apply mutation tool, the agent has everything needed to sequence the calls.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: `header_map` omission versus passing it defines the preview/apply split, and the response fields `already_mapped`, `sample_rows`, and `is_valid_for_job_type` are given operational meaning. `has_header` is only loosely covered ("applied with header_map").

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 ("Map a REACH list's columns to the input fields a job type reads") plus the downstream purpose (so `create_job` can run). It clearly separates this tool from siblings like `create_job`, `preview_list`, and `show_list` by naming their roles 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?

Provides an explicit three-step workflow with a no-op first call, when to consult `sample_rows`, when to apply `header_map`, and when to hand off to `create_job`. It also states exclusions: REACH-generated lists keep their mapping, while only Data Workbench output and b2b2c_append-style lists accept a new one.

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 idempotentHint=trueais, so the safety profile is covered. The description adds value by specifying the exact scope of the result – one list plus summary of latest job – which goes beyond the annotations. 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?

Two sentences, front-loaded with what it returns and when to use it. No wasted words.

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

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

For a one-parameter, read-only, idempotent tool with an output schema, the description plus annotations fully cover what an agent needs to know. It states scope, return content, and selection condition.

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

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

Input schema covers the single parameter with type, minimum, and a description that already conveys the list ID must be a positive integer. The description adds no extra semantics but none are needed at 100% coverage.

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

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

States a specific verb ('Show') and resource ('one REACH list') plus what it returns ('summary of its latest job'). Distinguishes itself from sibling tools by requiring a known list ID and returning full metadata, which separates it from preview_list and list_lists.

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?

Explicitly says when to use the tool: when the list ID is already known and full metadata plus job status is needed. It doesn't name the alternatives it excludes (e.g., list_lists, job_status), but the context is clear enough for an agent to route to 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 confirm read-only, non-destructive, and idempotent behavior. The description adds detail about the output nature ('small summary', 'counts', 'recent-list preview'), giving further clarity without contradicting 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 concise, using two short sentences with no redundant information. It is well-structured and directly addresses the tool's purpose and usage.

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?

While an output schema exists (so return values need not be detailed), the description gives sufficient context about what the summary contains ('counts', 'recent-list preview'). It is complete enough for an agent to understand the tool's functional scope, though edge cases like error handling are not mentioned.

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 only parameter project_id is fully described in the schema with type and constraints. The description does not add extra semantic meaning beyond 'Positive integer project ID', so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: showing one REACH project and a summary of its lists. It distinguishes from sibling tools like list_projects by specifying a single project and the inclusion of list summaries.

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 usage condition is given: 'Use this tool when you already know the project ID and need counts plus a recent-list preview.' This clearly indicates when to choose this tool over alternatives.

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