Vepathos

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

Goes well beyond annotations. The description explains idempotency ('the same one twice returns the same rule'), the always-SWITCHED-OFF state, that it costs no plan stops, and gives guidance on how to describe it to users ('never say it is running', 'give them account_url'). This adds substantial behavioral context not present in annotations. No contradiction.

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

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

The description is a dense paragraph of about 150 words, but every sentence adds essential information. It is front-loaded with purpose and then logically organizes parameter decisions, behavioral notes, and user-facing guidance. While long, it is not verbose given the tool's complexity.

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

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

With an output schema present, return values are covered. The description addresses core invocation decisions (batch source, schedule, idempotency), operational constraints (switched off, no cost), and user communication hints. It is complete for an agent to call this tool correctly without additional external knowledge.

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 documents all parameters. The description adds meaning by explaining parameter relationships (e.g., choice between use_plan_stops and integration_account_id) and the significance of template_plan_id being copied. It doesn't cover every parameter, but the added context for key decisions is valuable.

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

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

The description opens with a specific verb+resource: 'Prepare a rule that routes deliveries on a schedule.' It clearly distinguishes this from siblings like list_automations or optimize_routes, and the subsequent detail on template copying and schedule definition reinforces the unique 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?

Provides clear context on how to use the tool: where the batch comes from (use_plan_stops vs integration_account_id), when it looks (looks_at vs window_from/window_to with every_minutes), and the idempotency of operation_id. It doesn't explicitly name alternatives or state when not to use it, but the guidance is sufficiently clear for an agent to select it appropriately.

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 description goes far beyond the annotations: it discloses anonymous public access, 48-hour expiry, repeated calls returning the same link without extending it, and no additional optimization/charge. It also adds UI language behavior, which contextually explains what idempotentHint=true means in practice.

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?

Though multi-sentence, every sentence carries a distinct behavioral or usage constraint; nothing is filler. The opening sentence states the core purpose before the caveats, making it easy to scan.

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

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

The description covers selection criteria, privacy exposure, expiry, re-call idempotency, cost, and language handling. An output schema exists for return values, so there is no significant missing context for an agent to call 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?

With 100% schema coverage, the schema already documents syntax and origin of both parameters. The description adds value by saying language should be the conversation language and controls the page/share message/PDF language, and that optimization_id must refer to a completed optimization from optimize_routes, but the schema already covers much of this.

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 names a specific action and resource: 'Create a temporary public link to the map of a completed optimization owned by the connected account.' This clearly separates it from sibling tools like optimize_routes or get_optimization_result, so an agent knows it is about sharing a finished map.

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 decision rule: offer the account plan and the link, and 'create the link only when the user picks it.' It also states what the tool does not do ('Does not optimize again or charge stops'), preventing misuse as a rerun-optimization tool. This is as concrete as naming a sibling alternative.

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 description adds significant behavioral context beyond the annotations. The annotations already indicate idempotentHint=true, but the description explains that the tool carries only addresses and silently drops any additional data, which is a critical behavioral trait not captured by annotations. It also discloses quota consumption ('Charges Smart Import quota, not route stops') and the return behavior (returns pins or geocode_id for get_geocode_result). However, it does not explicitly mention error handling or edge cases like invalid addresses, and it relies on annotations for idempotency, so a score of 4 is justified—strong but not perfect.

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 relatively long but each sentence serves a purpose: it states the core function, requirements, output behavior, quota implications, constraints on data, and routing to siblings. It is front-loaded with the primary function and critical usage note. While it could be tightened slightly, the length is justified by the need to convey the strict data limitation and alternative routing, making it efficient for an agent to parse. A score of 4 is warranted given the density of information without redundancy.

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

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

Given the tool's complexity (5 parameters, nested objects, output schema), the description is remarkably complete. It explains the mutual exclusivity of depot and city, the return mechanism (pins or geocode_id for async retrieval), the matched_address for quality check, the need to handle needs_confirmation, and the strict data policy. The output schema exists, so return values are covered. There's no missing information an agent would need to call it correctly, making a score of 5 justified.

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 coverage is 100%, with every parameter having a description in the schema. The tool's description adds value by contextualizing the depot and city parameters: 'Requires a depot lat/lng or a city' clarifies the mutual dependency between these fields, which is not obvious from the schema alone. It also explains that each stop includes matched_address, which relates to the output, not directly to parameters. Since the description adds meaningful context beyond the schema (like the requirement to provide either depot or city), a score of 4 is appropriate, exceeding 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 tool's purpose: 'Turn street addresses into latitude/longitude using Vepathos Smart Import.' It specifies the resource (addresses), the action (geocoding), and the key outcome (returns pins or geocode_id). It also distinguishes itself from its sibling import_deliveries by stating that this tool only handles bare addresses and drops any additional delivery data, making the purpose and scope unambiguous. The description is specific and not a tautology.

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 explicit guidance on when to use this tool versus its sibling import_deliveries: 'Rows carrying any of those are a delivery list, however few, and go to import_deliveries, which keeps them and geocodes them itself. Use this one for bare addresses: checking a handful, or placing a depot.' It also gives clear exclusions: 'a customer, phone, package count, weight, volume, note or delivery window sent here is dropped without a word.' This is a textbook example of when-not to use and provides a direct alternative, which is essential for agent selection.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive; the description adds meaningful context beyond that: it takes no arguments, derives the account from the connection, and does not consume plan stops. It also explicitly warns the agent not to claim the account is invisible or that no profile tool exists, which is useful behavioral 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?

The description is front-loaded with output scope, no-arguments, and read-only behavior, then moves into usage and troubleshooting. It is wordier than needed for a zero-parameter getter, but each sentence carries actionable guidance, including what not to claim and how to respond when the wrong account is connected.

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

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

For a zero-argument read-only tool, the description is complete: the output schema covers return values, annotations cover safety, and the description covers invocation, when to use it, and post-call failure diagnosis. Nothing needed to select or call the tool 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?

There are zero parameters and the schema description coverage is 100%, so there is little to document. The description still adds valuable semantic context by stating 'Takes no arguments' and explaining that the account comes from the connection itself, preventing an agent from inventing an account parameter.

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 ('Show which Vepathos account this connection uses and what its plan allows') and enumerates the exact fields returned. It is clearly distinct from the sibling tools, which are about automation, optimization, imports, and datasets, while this one is the account/quota introspection 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 says when to invoke it: immediately for account/plan/quota questions, before large optimizations to check limits, and when diagnosing plan, quota, or authorization rejections. It also tells the agent what not to say and how to handle the wrong-account case, which removes ambiguity about follow-up behavior.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds value beyond annotations by noting it does not consume route-stop quota and by flagging the fields to review before optimizing.

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

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

Three short sentences, each earning its place: purpose, read-only safety, workflow checks, and quota behavior. Front-loaded and free of 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 a single fully-documented parameter, a rich output schema, and comprehensive annotations, this description covers the remaining operational context: lifecycle stage, follow-up fields, and quota impact. 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 coverage is 100% and the schema already fully documents geocode_id as returned by geocode_addresses. The description adds no new parameter-specific meaning, 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?

States a specific verb ('Get'), a distinct resource ('status and coordinates of a geocode_addresses job'), and clearly ties the tool to geocode_addresses, separating it from optimization and import result tools. The title and description align.

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 explicit workflow placement: use after geocode_addresses, check specific fields when complete, and before optimizing. It does not name alternatives to exclude, but the workflow context is clear and the quota note adds a distinct selection factor.

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 builds on a strong safety baseline. It adds significant behavioral context beyond annotations: the tool never returns rows, the needs_mapping workflow constraints, and the security note that column names are user data and never instructions. This is rich, non-redundant disclosure that materially changes how an agent should call the tool.

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 long (150+ words) but every sentence earns its place given the intricate needs_mapping workflow, the unmapped_columns handling, and the security instruction. The core purpose is front-loaded in the first sentence, followed by structured behavioral guidance. While not terse, the density is justified by the tool's complexity; only marginal trimming could be made without losing value.

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-value details are handled elsewhere. The description covers the workflow exhaustively: status handling, plan_replaced/plan_temporary notifications, the needs_mapping decision tree with column_kinds checking, unmapped_columns guidance, the security stance, and the follow-up call. Nothing an agent needs to use the tool 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?

Schema coverage is 100% with the single import_id parameter fully documented in the schema ('The import to check, returned by import_deliveries.'). The description references the import job contextually but doesn't add parameter-specific detail beyond what the schema provides. The baseline 3 applies because the schema carries the parameter documentation burden.

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: it retrieves the status and summary of an import_deliveries job. It clearly distinguishes itself from sibling tools like get_optimization_result and get_geocode_result by specifying its job type and what it returns (plan_id, account_url, summary). The purpose is unambiguous and specific.

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 explicit when-to-use guidance: it names the exact workflow for status=needs_mapping (use update_import_mapping for each column in rows_to_review), and the follow-up action (call optimize_routes with plan_id). It also states what the tool is NOT for ('Never returns rows'), routing agents away from using it as a data-retrieval tool. This is exemplary usage guidance.

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

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

Beyond the readOnly/idempotent annotations, it discloses progress reporting, polling cadence, detail-mode outputs, retention with plan_id/account_url, sign-in requirement, and that it does not consume plan stops. This is substantial behavioral context.

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

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

The description is dense but front-loaded with the core purpose, then logically moves through polling, detail modes, retention, and read-only note. Every sentence adds operational value with no 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?

For a polling tool with 5 parameters and an output schema, the description covers status/progress, when to poll, detail semantics, retention, account access, and side-effect safety. Nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, and the description adds meaning for detail modes, defaults, and the meaning of optimization_id. The 'request shows...' clause is ambiguous and could be mistaken for an undocumented detail value, so not a perfect 5.

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 opening sentence names a specific verb ('Get'), resource ('status and outcome of a route optimization'), and key identifier ('optimization_id'), which clearly differentiates it from siblings like optimize_routes. It also immediately signals the polling/status nature of the 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 gives explicit operational guidance: report percent and stage in one line and wait poll_after_seconds before polling again. It does not name alternative tools or exclusion conditions, but the context makes the intended use clear.

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

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

The description discloses significant behavior (geocoding, creating/replacing plans, polling pattern, restrictions), but it directly contradicts the annotation destructiveHint: false because it states 'replace the stops of plan_id', which is a destructive side effect. Per rules, score 1 and flag annotation contradiction.

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 lengthy but every sentence carries operational weight. It front-loads the core purpose and then systematically covers inputs, exceptions, and the follow-up workflow. It could be trimmed slightly, but the details are essential for a complex tool with multiple input modes and integration points.

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 (7 params, nested file object, output schema, many siblings), the description is remarkably complete. It covers all input modes, local file handling, conversion limitations, the geocoding behavior, plan creation/replacement, and the async result polling pattern. It also explains when to use other tools (geocode_addresses, list_plans, optimize_routes). Nothing an agent needs to call 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?

Schema coverage is 100%, so baseline is 3. The description adds substantial value beyond the schema: clarifies that file is host-provided and never hand-built, explains when each source (file/url/text) is appropriate, notes that a path is not a url, and explains the filename default and purpose of timezone and depot_country. These add meaningful usage semantics.

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: 'Import deliveries into Vepathos'. It differentiates from siblings by explicitly noting it geocodes addresses so they skip geocode_addresses, and that row attributes survive only here. This gives the agent a precise understanding of what this tool is for and why it exists.

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 provides explicit when-to-use guidance: describes the three input sources (file, url, text) and conditions for each, including host capabilities and file types. It also directs alternatives for spreadsheets (ask for share link or upload) and states what not to do (shell out, parse with script). It even mentions routing to list_plans and optimize_routes for saved plans, making selection unambiguous.

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 readOnlyHint and idempotentHint, and the description adds meaningful behavioral detail beyond them: it never consumes plan stops, and it explains the empty=true and plan_missing=true flags, including the consequence that a plan_missing automation cannot run until fixed in the dashboard.

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 dense but every clause earns its place: it front-loads the core purpose, lists the salient fields in a compact enumeration, and ends with the two important output flags. It is thorough without becoming padded or redundant.

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

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

Given zero parameters, rich annotations, and an output schema, the description fully covers what an agent needs: the scope (account), the no-argument nature, read-only status, plan-stop cost, and the meaning of special output states. Nothing essential is missing.

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

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

With zero parameters and schema coverage at 100%, the description still adds value by explaining that the tool implicitly answers for the account the credential belongs to. No parameter documentation is needed beyond this, and the schema already states 'No arguments'.

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

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

The description names a specific verb-resource pair ('List the connected Vepathos account's standing rules') and enumerates the exact details returned, making it clearly distinct from siblings like list_plans or list_fleet. It also notes it returns connected stores, tying it to create_automation's input without confusing it with account-level 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 clearly states this tool takes no arguments, is read-only, and does not consume plan stops, which guides safe usage. It does not explicitly say when to prefer this over alternatives like list_plans, but the focused resource and sibling context make the intended use clear.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds 'Read-only' which is redundant but consistent. It describes the returned content but not behavioral aspects like pagination or error behavior. With annotations covering safety, the description adds modest value.

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?

Single sentence but dense; front-loaded with purpose, then details return fields. No fluff, but could be split for readability. Still appropriately concise.

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 details are covered. The description adds scope and intended use. It's complete for a simple list tool with annotations covering safety.

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% with limit parameter described in schema (max, min, default, 'newest first'). Description doesn't add extra meaning beyond what's in schema, so 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?

States a specific verb (list) and resource (imports from this or earlier chats), and enumerates the returned fields (plan_id, charged status, last_run). Distinguishes from siblings like list_plans and list_automations by focusing on imports.

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?

Implied use case for listing imports to repeat or vary optimizations, but does not explicitly contrast with alternative tools like get_import_result or list_plans. No when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable behavioral details beyond those: 'it does not consume plan stops', 'empty=true means the account has no vehicles saved', 'A vehicle with no capacity means the account never set one, not that it carries nothing', and the note that one-run vehicles are not saved. These clarify return semantics and data interpretation, making the tool's behavior much more transparent.

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

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

The description is dense but all sentences carry necessary information. It front-loads the core purpose, then covers side effects, empty states, capacity semantics, and unsaved vehicles. The main sentence is long with multiple parenthetical clauses, slightly reducing readability, but every part earns its place and there is no 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 zero parameters, read-only annotations, and the presence of an output schema, the description is exceptionally complete. It covers edge cases (empty account, null capacity), clarifies the relationship to optimize_routes and manage_catalog, and explains what is NOT included. An agent has everything needed to invoke and interpret 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 tool has zero parameters and the schema coverage is 100%, so the baseline is 4. The description reinforces this with 'Takes no arguments' and explains that the catalog belongs to the connected account, which adds minimal but sufficient context. There is no parameter documentation burden to compensate for.

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: 'List what the connected Vepathos account has saved: vehicles and fleets ... and depots'. It specifies the exact resource (catalog contents) and provides differentiating details about the IDs returned and their role in optimize_routes, distinguishing it from siblings like manage_catalog and optimize_routes.

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 concrete usage context: it is read-only, takes no arguments, and does not consume plan stops. It also provides conditional guidance: when empty=true, ask the user and save via manage_catalog; vehicles for one run should be passed to optimize_routes. While it does not explicitly state 'use this instead of X', it clearly implies when this tool is appropriate and routes to alternatives for specific cases.

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 description goes well beyond annotations by adding detailed behavior: without plan_id returns favorites/newest and library size, replacement policy; with plan_id returns stop counts, depot, next run charges, tries, etc.; explains account_url sign-in; confirms read-only and 'never returns stops.' This adds significant context that annotations only hint at (readOnlyHint) and provides operational nuances.

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?

Although lengthy, the description is dense with necessary information, front-loaded with the main purpose and then systematic breakdown of modes. Every sentence adds value—no filler, and the structure (purpose, mode-specific behavior, user-summarization rules, usage exclusions, follow-up action) makes it easy to scan.

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

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

The description covers both operational modes, user-facing summarization semantics, edge cases (library replacement), authentication for account_url, and cross-tool routing to optimize_routes. Given the tool's complexity and the presence of an output schema, this is complete—nothing an agent needs to call and interpret results 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 coverage is 100%, but the description adds deeper meaning: explains how limit behaves (favorites first), query filters by name, and plan_id triggers a different return set including last_agent_run. It also clarifies the meaning of next_optimize_charged in the output, which is not in the schema but essential for correct user summarization.

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 explicitly states 'List the plans in the connected Vepathos account' and differentiates behavior with and without plan_id. It also distinguishes itself from sibling tools by noting it is for saved plans, not scheduled tasks, and names alternatives when needed. This is a specific verb+resource with clear scope.

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 explicit when-to-use guidance: 'If they ask for their Vepathos tasks, jobs or functions, call this (saved plans), not the host's scheduled-task list' and 'To rerun or vary one, confirm last_agent_run with the user and call optimize_routes with plan_id.' It also explains summary behavior with next_optimize_charged, giving clear context on when to use this versus alternatives.

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

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

Annotations already declare destructiveHint and idempotentHint, but the description adds substantial behavioral detail: duplicate creation returns already_existed or NAME_TAKEN, update replaces the whole fleet list, omitted fields remain unchanged, and the agent must say what will be saved and get a yes first. It also clarifies that the tool does not consume plan stops. 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?

The description is dense but every sentence earns its place: purpose, call conditions, exclusions, resource-specific constraints, action-specific behavior, and confirmation requirement. It is logically ordered and front-loads the core distinction between catalog data and plan settings.

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

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

For a tool with 9 parameters, two enums, and an output schema, the description covers all resource/action combinations, required fields, duplicate-name outcomes, update semantics, and user confirmation. The output schema handles return-value documentation, so no important 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 100%, so the schema already documents each parameter. The description adds meaningful cross-parameter workflow beyond the schema: which resource accepts which fields, that depot coordinates must come from geocode_addresses, that fleet vehicles must already be saved and referenced by id, and that update requires resource_id. This justifies above-baseline but not the top score since field-level descriptions are already in 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?

The description opens with a specific verb-resource pair ('Add or change a vehicle, a depot or a fleet saved in the account') and distinguishes persistent master data from transient plan settings. It explicitly differentiates from sibling tools like optimize_routes and geocode_addresses, so an agent can route correctly without opening schemas.

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 explicit call conditions with concrete user phrases ('add a 1,500 kg Sprinter', 'make a fleet called norte with 6 vans') and states clear exclusions: plan-level capacity, depot-for-today, and 'use 25 vehicles' are plan settings to pass to optimize_routes, never catalog mutations. It also names the sequencing dependency on geocode_addresses and list_fleet.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description discloses the charging model ('A run spends one monthly stop per stop'), the 'otro intento' retry semantics, deduplication of identical arguments, rejection behavior, plan persistence/replacement effects, and the requirement to tell the user when plan_replaced or plan_temporary is set. This far exceeds what annotations alone convey. No contradiction with annotations is present.

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

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

The description is long, but every sentence carries operational value for an 18-parameter, billing-sensitive tool. It is appropriately front-loaded with the core purpose and then covers sources, charging, exceptions, and post-call behavior. It is somewhat dense as a single monolithic paragraph, which prevents a 5, but there is 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, destructive/charging behavior, and rich output schema, the description covers everything an agent needs: stop source selection, depot formats (including telling the user about depot_resolved), charging and retry rules, consent-before-call, deduplication, rejection conditions, plan lifecycle, required route_start_time, and how to obtain results. Nothing essential 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 coverage is 100%, so the baseline is 3, but the description adds meaningful semantic clarity: the exclusivity of the three stop sources, the persistence differences between plan_id/dataset_id and stops, that route_start_time is needed for arrival times, and that max_route_minutes is a target rather than a hard limit. These nuances go beyond the schema property 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?

The description opens with a specific verb and resource ('Plan delivery routes (vehicle routing problem, VRP)') and precisely states the objective: assign stops to vehicles, sequence routes from one depot, and minimize distance subject to capacity and time-window constraints. It also distinguishes itself from sibling tools by referencing get_optimization_result for polling and import_deliveries for file/list/address-based stops.

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 explicit routing guidance: exactly one source of stops (plan_id, dataset_id, or in-conversation stops), with files/lists/addresses explicitly directed to import_deliveries first. It also mandates a precondition ('first tell the user the stops it charges... get a yes, then call once') and points to get_optimization_result for retrieval, making when-to-use and when-not-to-use unambiguous.

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=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it returns an updated summary and emphasizes that rows are not converted, which is useful behavioral context beyond the annotations. No contradiction.

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 sentences, all substantive, with the core purpose front-loaded and the critical unit-correction instruction near the end. No filler or redundant restatement of the title.

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, a fully documented input schema, and annotations covering idempotency and safety, the description supplies the missing behavioral context (no row conversion) and usage decision. Nothing an agent needs to call this 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?

Schema description coverage is 100%, so the schema thoroughly documents the mapping object and its unit/format fields. The description adds the high-level mapping shapes and the 'never convert rows' nuance, but the schema already carries most semantic weight, so a 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?

States a specific verb ('Correct'), a specific resource ('an import's column mapping'), and the key constraint 'without re-uploading', which distinguishes it from import_deliveries and get_import_result. The purpose is unambiguous and actionable.

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

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

Gives explicit direction on when to use it ('When the user corrects a unit') and an explicit exclusion ('never by converting the rows yourself'). It also implies the alternative of re-uploading is not needed, which is clear guidance for agent selection.

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