kubik-tools

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read operation. The description adds substantial behavioral context: rounding rules (UP to nearest 0.5 kg for air/courier, no rounding for road/sea_lcl), edge-case handling (returns structured explanation, never guesses defaults), and the output object's contents.

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 earns its place. It is structured with clear sections: formula, per-mode divisors, a worked example, rounding, edge cases, and returns — making it easy to scan while being exhaustive.

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

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

With no output schema, the description fully enumerates return fields (total actual weight, total volume, volumetric weight, raw/rounded chargeable weight, governing dimension, divisor, summary). It also covers edge cases and mode-specific behavior, making the tool safe and predictable to invoke.

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 already has 100% coverage, but the description adds meaning: explains how mode selects divisors, how volumetric_divisor overrides defaults, and provides the actual formulas (e.g., volume_cm3 / 6000). It also explains the distinction between chargeable_weight_raw_kg and chargeable_weight_kg.

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

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

The description clearly states a specific verb ('Calculates chargeable (billable) weight') with a defined resource (freight shipment from cargo pieces across four transport modes). It also differentiates from sibling tools by explicitly directing loading-metre questions to calculate_loading_metres/check_truck_fit.

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 this tool for chargeable weight calculations and provides direct alternatives for loading-metre/vehicle-fit scenarios: 'for loading-metre, Stellplätze, or vehicle-fit questions, use calculate_loading_metres and check_truck_fit instead.' It also names the four applicable modes.

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?

Even with annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds rich behavioral context: unknown vehicle_id returns a list instead of guessing, missing weight yields null for total_weight_kg, max 100 piece lines, and the fixed 240cm reference width. No contradictions.

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 and front-loaded with a clear opening sentence, but it is quite long and repeats some vehicle_id behavior already present in the schema. Every sentence adds value, though the length could be slightly reduced without losing 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?

Given the absence of an output schema, the description thoroughly covers all relevant return values (LDM, pallet places, deck_length_m, total_weight_kg) and edge cases. It also includes the formula, units, and a worked example, making it complete for an agent to invoke 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%, but the description adds meaningful semantics beyond it: the formula, worked examples, and optionality/behavior of weight and vehicle_id. While the schema already documents the fields, the description reinforces how values are used in the calculation.

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 calculates loading metres (LDM) and pallet-place equivalents, with specific verb, resource, and scope. It also explicitly differentiates from calculate_chargeable_weight, making it distinct from siblings.

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 guidance on when to use the tool (floor-space questions, not volumetric weight) and names the alternative tool for volumetric/chargeable weight. Also explains when vehicle_id is relevant (to get deck_length_m).

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?

Even though annotations already declare readOnly and idempotent hints, the description adds substantial behavioral context: it explains that payload check is honestly skipped if weight is omitted, that recommended_vehicles are suggestions never auto-picked, that utilization percentages are uncapped intentionally, and that invalid vehicle IDs return the full list rather than guessing. No contradictions 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 long but well-structured with clear sections: intro, vehicle profiles, units, modes, example, and edge cases. The first sentence immediately states the core purpose, and each section earns its place given the tool's complexity. It is slightly verbose, but no sentence is wasted; a 4 is appropriate for this density of necessary 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?

Despite having only 2 parameters and no output schema, the description covers all necessary context: input modes, units, vehicle profile mapping, edge cases (unrecognized ID, no fitting vehicle), limits (100 pieces), and even an example. The tool's behavior across all possible input combinations is fully documented, making it complete for an agent to invoke 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%, giving the baseline 3, but the description significantly enriches both parameters. It explains the meaning of pieces as lines with quantity, provides units (cm, kg), clarifies weight_kg_per_piece as optional, and details how vehicle_id maps to German names and behavior when omitted. It also provides a worked example that demonstrates parameter usage, far exceeding schema 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 clearly states the tool checks cargo fit against vehicle capacity limits (loading metres and payload), with a specific verb ('checks') and resource ('list of cargo pieces fits a named vehicle'). It explicitly distinguishes itself from full 3D placement or load securing, and from sibling tools like calculate_loading_metres. The purpose is unmistakable 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 provides explicit usage guidance by defining three modes based on input combinations: vehicle_id + pieces for full check, vehicle_id alone for spec lookup, and no vehicle_id for listing vehicles. It also tells users when this tool is appropriate versus alternatives by excluding 3D placement and load securing, and by referencing sibling tools implicitly through the mention of loading metres. This is exemplary 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 only provide negative hints (not readOnly, not idempotent, not destructive), so description carries full burden. It discloses the two-step workflow, that the tool is never a silent write, that parameters are ignored on the confirm call except api_key/confirm/preview_id, that the duplicate check only runs on the first call, and that creation is team-visible immediately. This is rich, non-obvious behavior.

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 well-organized, front-loading the core purpose and then explaining the two-step design, parameter behavior, and exclusions. Each paragraph earns its place, though the final required/optional list somewhat duplicates schema information. Slightly verbose but justified by 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?

Despite having no output schema, the description conveys the preview/confirm response flow, duplicate-check behavior, undo timeframe, and team-scoped visibility. It fully addresses the tool's complexity, including the subtle behavior that only preview_id and confirm matter on the second call, leaving no ambiguity about how 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 covers most parameter descriptions, but the description adds critical interplay semantics: only api_key, confirm, and preview_id are read on the confirm call, all other fields are ignored if resupplied, and preview_id is required when confirm=true. It also clarifies hs_code must be exactly 8 digits and reiterates required/optional fields. This goes well beyond schema 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 'Creates a new article in your team's kubik.tools Library', using a specific verb and resource, and immediately clarifies team-scoping. It distinguishes itself from sibling tools by explicitly stating it only creates article records, never packing data (unlike log_pack_observation).

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 when-to-use guidance: 'Do not use this to log a real packing observation... use log_pack_observation instead'. Also explains the mandatory two-step preview/confirm flow and warns against skipping the unconfirmed call, plus mentions undo_change for reversal within 15 minutes.

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 are all false/neutral, so the description carries the full burden of behavioral disclosure. It richly describes the two-step design, the confirm-call field-ignoring behavior, the 15-minute undo window, append-only permanence, and the fact that it cannot create a new group. No contradictions 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 long but every sentence earns its place: it starts with the core function, then the workflow, then field semantics, exclusions, and prerequisites. It is well-structured and information-dense without waste, appropriate for a complex tool with 10 parameters and a two-step flow.

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 10 parameters, no output schema, and non-trivial behavioral rules, the description covers purpose, flow, field roles, undo/persistence behavior, exclusions, and prerequisites. The only minor gap is the exact preview response shape, but the description indicates what the preview is for and returns preview_id, which is sufficient for the agent to use 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?

Schema coverage is 70%, and the description adds meaningful context by explaining which fields are read on confirm (api_key, confirm, preview_id), showing an example for member_quantities, and clarifying preview_id's role. The three dimension params (length_cm, width_cm, height_cm) lack individual descriptions, but their names and units are self-explanatory and the description refers to 'dims/weight', so the meaning is adequately conveyed.

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: 'Logs a real, observed consolidation pack...against an existing consolidation group in your team's Library.' It clearly distinguishes this from sibling tools by stating it produces ground-truth data for resolve_quantities and explicitly says 'Do not use this for a single article's own packing history' and 'Do not use this to correct a mistaken past observation,' making the purpose unambiguous.

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

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

The description gives explicit when-to-use context ('real, observed consolidation pack'), prerequisites (existing consolidation_groups id, article numbers), and when-not-to-use exclusions (single-article history, post-undo corrections). It also explains the two-step preview/confirm flow and references alternatives like undo_change, providing complete 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?

The description explains in detail the resolution_status values ('resolved', 'ambiguous', 'not_found') and what each means, including how to handle 'ambiguous' (present options to the user, not guess). It also describes tier values ('observed', 'estimated', 'verify') with their implications and notes the backward-compatibility needs_confirmation field, providing rich behavioral context beyond the sparse 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 long but well-structured, with clear sections for purpose, status handling, tiers, exclusions, and auth. Every sentence adds necessary behavioral detail, though the backward-compatibility note could be trimmed; it is not as tight as a two-sentence description but remains efficient for the 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?

Given there is no output schema and only three parameters, the description effectively explains all return semantics (units, tier, alternatives, needs_confirmation) and when they apply. It also covers exclusion cases and authentication, making it highly complete for a tool with this complexity.

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% for all three parameters, so the schema carries the load. The description adds minor context about the api_key (team-scoped Bearer token) and article_query (looks up by number or name within the team's Library), but largely repeats schema information, so it does not significantly raise the baseline.

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

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

The description clearly states a specific verb and resource: 'Resolves an ordered quantity of a Library article into concrete packed units (boxes/pallets)' and explicitly distinguishes from a sibling concern by excluding prepack-table and consolidation-group quantities. It provides a concrete outcome and avoids any 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 gives explicit guidance: check resolution_status first, do not autonomously choose when ambiguous, and clarifies that prepack/consolidation quantities use a different tool. It also states the API key requirement and team scoping, which are actionable usage prerequisites.

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?

Although annotations already mark destructiveHint=true, the description adds essential behavioral detail: refusal conditions for dependent article_profiles, the append-only nature of consolidation_pack_observations, and the design rationale referencing PRINCIPLES.md. 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 appropriately sized for a tool with significant constraints. The first sentence front-loads the core action, and the subsequent paragraphs efficiently explain exceptions and design rationale without 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 is destructive, has no output schema, and handles two distinct table types, the description covers behavior, constraints, refusal cases, and rationale well. It doesn't describe the return value/success response, but the rest is complete enough for an agent to use safely.

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 already describes all three parameters thoroughly (100% coverage), so the description adds limited extra parameter meaning. It does add a useful mapping between the 'table' enum and the originating call, but this is modest 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?

The description clearly states it 'Undoes a create_article_profile or log_pack_observation call', naming specific verbs and resources. It also distinguishes this tool from its siblings by emphasizing that it is only for undo, not for general editing/deleting.

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 usage boundaries: only within 15 minutes of confirmation, only if nothing depends on it, and never as a general edit/delete capability. It also names the alternative path: 'edit it or delete it manually in the app instead of undoing'.

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