clm-mcp

by sabadia

Overview Schema Source Related Servers Score Discussions Admin

Python

Hybrid

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation2/5
Multiple tool boundaries are unclear: the regular and Smart Shipment wizard step tools differ only by prefix, clm_shipment_command_delete_draft_shipment is described as a status transition that collides with clm_shipment_command_update_shipment_status, and the generic clm_invoke overlaps with many concrete write tools. Agents would need to read long descriptions very carefully to reliably pick the intended tool.
Naming Consistency4/5
The naming follows a strong clm_<domain>_command_<verb>_<object> pattern for writes and clm_list_/clm_get_/clm_count_ for reads, with consistent snake_case throughout. Minor deviations include clm_whoami, the generic clm_invoke/list/describe tools, and the misleading delete_draft_shipment name that does not match its described behavior.
Tool Count1/5
With 82 tools, the surface is far beyond a well-scoped MCP server, and it includes near-duplicate wizard variants, many overlapping status/comment/update commands, and a generic invoke escape hatch. This imposes a severe context and selection burden on agents and is an extreme count for practical use.
Completeness4/5
The set provides broad lifecycle coverage for shipments, equipment, incidents, lean cards, material handovers, reports, and user filters, with no obvious dead ends for the main workflows. The main gaps are first-class reference-data lookups such as listing teams, zones, materials, and vehicles, though the generic invoke/describe tools can partly work around these.
Average 3.9/5 across 82 of 82 tools scored. Lowest: 1.3/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 2 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint=true annotation correctly signals that this is destructive, and the description does not contradict that annotation. However, the description's claimed behavior (status transition, grouping counts, background processing) appears unrelated to deleting a draft shipment, so it does not transparently disclose the actual destructive behavior. The annotation carries the only reliable safety signal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and reasonably compact, but most of its content is irrelevant to a delete-draft-shipment operation. The long parenthetical list of statuses and background-processing details adds noise and does not earn its place. A correct short description would be more concise and more useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description omits the core delete behavior, prerequisites such as the shipment needing to be a draft, and any caution about the destructive nature beyond the annotation. The output schema does not compensate for the mismatch. This is seriously incomplete for a destructive command with one required parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description says nothing about the ShipmentId parameter or how it should be provided. The parameter name is self-explanatory to a degree, but the description does not clarify that it identifies the draft shipment to delete or whether null is acceptable. With 0% schema coverage, the description needed to compensate and did not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description says the tool 'Transitions a shipment to a new status' and lists statuses, which is a status-update behavior, not a delete-draft-shipment behavior as the tool name states. It never mentions deleting, discarding, or removing a draft shipment, so it is misleading about the core purpose. It also fails to distinguish this from the sibling clm_shipment_command_update_shipment_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs alternatives. It does not state that this is for deleting a draft shipment, nor does it explain when another command like discard_shipment or update_shipment_status should be used instead. The status-transition language actively suggests using it for a purpose likely handled by a sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover idempotency and non-destructiveness. The description adds that the operation is a write operation, which is a useful mutating-behavior signal not explicit in the annotations. However, it does not describe side effects, prerequisites, or what statuses are valid, so it adds only minimal behavioral context beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but mostly restates the tool name; the only substantive addition is 'a write operation.' This is under-specification rather than effective conciseness, since not enough information is packed into the sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even with an output schema and non-contradictory annotations, the description is too thin for a tool with eight nested parameters and many sibling shipment commands. An agent cannot determine valid parameter combinations, triggering business scenarios, or how this differs from other shipment mutation commands.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needed to compensate for the undocumented nested parameters. It does not explain ShipmentId, Status, DiscardComment, CompletedEquipments, CancelledEquipmentIds, or any parameter relationships, leaving an agent without the information needed to construct a correct call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description is essentially a restatement of the tool name: 'Execute ShipmentCommand/UpdateShipmentStatus' maps directly to clm_shipment_command_update_shipment_status. It adds only the generic label 'a write operation' but does not explicitly say that it changes a shipment's status or what entity/state is affected.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not explain when to use this tool instead of related shipment commands such as clm_shipment_command_discard_shipment, delete_draft_shipment, or update_shipment_comment, and there are no context or exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description transparently explains that setting an address as not-favourite deletes it and that other cases update or create the address. However, this directly contradicts the annotation destructiveHint=false, since the description explicitly says the tool 'removes' and 'deletes' a saved address. Under the rubric, a contradiction with annotations mandates a score of 1.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The key action and resource are front-loaded, and the conditional deletion behavior is captured efficiently in a single sentence without filler. The parenthetical and 'otherwise' clause make it somewhat dense, but every clause contributes necessary operational detail. It earns a 4 for being concise and structured around the most important behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool exposes 14 optional-looking address parameters, but the description does not explain which are needed for create versus update, which fields are semantically required, or how the address fields relate to the delete path. The conditional deletion is disclosed, but the annotation contradiction and the largely undocumented parameter vocabulary leave meaningful gaps. An output schema exists, so return values are covered, but invocation confidence remains low.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to ItemId (identifier), TeamId (scoping team), and IsFavourite (delete vs. upsert), which the bare schema does not provide. With 14 nested properties and 0% schema description coverage, most fields like Country, Distance, Latitude, Longitude, StreetName, AddressLabel, and DistanceUnit remain unexplained. This is only partial compensation for the large coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with specific verbs ('creates, updates, or removes') and a clear resource ('team's saved sustainability address'), making the tool's purpose unambiguous. It also states the conditional behavior: not-favourite deletes, otherwise update-or-create. This clearly distinguishes the operation from the many shipment-related sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for managing a team's saved sustainability address, but it does not explicitly state when to prefer this tool over alternatives or what conditions exclude its use. No sibling tool covers the same resource, so the lack of explicit alternatives is less harmful, but the guidance remains implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation already signals deletion/destruction, but the description adds no further behavioral context such as irreversibility, cascading effects, permissions needed, or whether the comment must exist. It simply restates the operation without enriching what the annotation already conveys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence that is immediately understandable. It contains no filler, repetition, or unnecessary detail, and the core verb and object are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the tool is simple and has an output schema, the description omits crucial context about the meaning of ItemId and any selection guidance. An agent has enough information to know deletion happens but not enough to confidently identify the correct comment target or know when deletion is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the ItemId parameter at all. The schema only provides the name, type, and default, leaving ambiguity about whether ItemId refers to the shipment ID or the comment ID. Since the description fails to compensate for the low coverage, the parameter semantics are under-specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Deletes') and the resource ('an existing shipment comment'), which distinguishes it from sibling tools like clm_shipment_command_create_shipment_comment and clm_shipment_command_update_shipment_comment. Even without reading the schema, an agent can tell what operation this tool performs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance about when to use this tool versus alternatives such as get_shipment_comments, create_shipment_comment, or update_shipment_comment. There is no mention of prerequisites, how to obtain the comment ID, or when deletion is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds valuable behavioral context beyond those annotations: it persists data, finalizes the shipment, and triggers a background command for post-save processing. This discloses a side effect that an agent would not otherwise know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and resource, then adds behavioral detail about persistence and the background command. It is compact with no real redundancy, though the parenthetical list makes it slightly dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a command with 13 optional nested parameters, no parameter documentation, and a finalizing side effect, the description is too thin. It does not explain the wizard flow, what each responsible-person object should contain, when SaveAsDraft matters, or what post-save processing entails. The output schema may cover return values, but the operational context is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only mentions on-site responsible person and sustainability/vehicle info plus the vague catch-all 'remaining shipment details.' It leaves many parameters undocumented: Comment, ShipmentId, BookingDate, SaveAsDraft, GroupingType, photos/documents, and the other responsible-person fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Saves the final other info step') and the resource ('the shipment wizard'), which distinguishes it from sibling wizard-step tools like booking_dates, material, timeslots, and unloadings. However, it does not explicitly differentiate itself from the smart-shipment variant, leaving some ambiguity at the sibling level.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrasing 'final step' and 'finalizing the shipment' implies it should be used last in the wizard flow, but there is no explicit guidance on prerequisites, when not to use it, or how it differs from the smart-shipment other-info tool. Usage context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, covering the operation's safety profile. The description adds useful context about the output being a grid scoped to active unloading zones, but it does not clarify how dates are aggregated, what 'active' means, or how the grid handles sites with no counts. This is acceptable 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler or redundant restatement of the tool name. It is front-loaded with the core output and scope, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only aggregation tool, the description plus annotations, full parameter documentation, and output schema are mostly complete. The main missing piece is explicit differentiation from similar count/summary/report tools, but the core invocation details are otherwise well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents site_id and the inclusive date-range parameters, so the baseline is 3. The description adds no parameter-specific meaning beyond reinforcing the weekly/date-window idea, which is already implied by the schema and tool name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource as a weekly shipment count grid for a site's active unloading zones, which is a specific output concept. It lacks an explicit verb such as 'retrieves' or 'lists,' but the tool name supplies the action, and the description distinguishes it from the broader shipment-count and cockpit-report siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to prefer this tool over alternatives such as clm_count_shipments, clm_get_shipment_summary, or clm_shipment_command_generate_cockpit_daily_report. No exclusions, context triggers, or alternative routing are mentioned, so the agent must infer usage from the name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate the operation is idempotent and non-destructive. The description adds limited context by clarifying that only the text is updated, not the comment as a whole, but it does not explain behavior when the comment does not exist or whether a null Comment clears the text.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. Every word contributes to stating what the tool does.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 0% schema description coverage, the description must compensate by explaining how to provide the comment identifier and new text. It does not do so, nor does it cover usage guidance. The output schema and annotations help, but the description alone leaves an agent guessing about required inputs and failure behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions for ItemId or Comment, so the description's mention of 'text' and 'existing shipment comment' adds some meaning. However, it does not explicitly map these concepts to the parameters or clarify which identifier is needed to locate the comment.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Updates') and a precise resource ('the text of an existing shipment comment'). It clearly distinguishes this tool from the sibling create and delete comment tools by specifying 'existing' and 'text.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus creating a new comment or deleting a comment. The word 'existing' implies it is not for creation, but no alternatives or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral context by disclosing that the request is asynchronous and returns immediately without waiting for generation. It does not contradict the destructiveHint annotation, though the annotation seems surprising for a report-generation tool; it also does not explain how or where the finished report will be delivered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the main action and resource before listing filters. It is reasonably concise with no filler, though the long filter enumeration makes it slightly dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the large number of parameters and the asynchronous pattern, the description is a minimal viable explanation but not complete. It omits how the agent should retrieve the generated report, whether a FileId must be supplied, and what the immediate response contains; the presence of an output schema mitigates this gap only partially.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only conceptually mentions filters for site, status, date range, team/equipment ids, and search keys. Many parameters such as FileId, Language, PageSize, Ascending, PageNumber, OrderByField, HasIncidentAnnotation, and HasDocumentationAnnotation are left completely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'queues', the resource 'Excel export of the site-equipment timeline', and the asynchronous nature of the operation. It also distinguishes this from the sibling generate_up_timeline_excel_report by specifying 'site-equipment' rather than 'up'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this should be used when an Excel export of an equipment timeline is needed, and it lists the available filters. However, it does not explicitly say when to use this tool versus the similar sibling generate_up_timeline_excel_report or the list_equipment_timeline read tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds day-wise granularity and single-shipment scope, but does not disclose additional behaviors such as timezone handling, status coverage, or ordering. This is acceptable for a simple read operation but does not go far beyond the annotation baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that states exactly what the tool returns. It is front-loaded with the key action and resource, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only tool with an output schema, the description is nearly sufficient. It lacks any indication of how this timeline differs from get_shipment_event_logs or when to prefer it, but nothing essential to invoking the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the shipment_id parameter already has a clear description ('The shipment's id.'). The tool description adds no parameter-level semantics, but none are needed for this single, well-documented parameter. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieve') and a concrete resource ('day-wise timeline for a single shipment'). This clearly distinguishes it from sibling getters like get_shipment_summary, get_shipment_comments, and get_shipment_event_logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives such as get_shipment_event_logs or get_shipment_summary. The description only defines the operation; it never states context, exclusions, or preferred use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful scoping context (daily records, site, date range, data fields), but it does not disclose details like default site behavior, timezone handling, or empty-result behavior. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, front-loading the key resource and constraints. Every part contributes to understanding what the tool returns and for whom.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only query tool with an output schema and 100% parameter schema coverage, the description is largely complete: it names the resource, scope, and data fields. Minor details like units, timezone, or date inclusiveness are not mentioned, but the structured schema and annotations cover most operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all four parameters clearly. The description adds the field names 'temperature, wind speed, symbol', which gives some hints about the fields parameter, but it does not meaningfully extend the schema's documentation of start_date, end_date, or site_id. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the unique resource (daily weather records) and the scope (site + date range), plus the contained data fields (temperature, wind speed, symbol). It is phrased as a noun fragment rather than an explicit action verb like 'retrieves', but the tool name and 'stored for a site within a date range' make the retrieval intent clear. There is no sibling weather tool, so sibling differentiation is not a concern.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when weather records for a site and date range are needed. However, it provides no explicit guidance about alternatives, exclusions, or when not to use it. Since no other weather-focused sibling exists, the usage context is inferable but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint, covering the safety profile. The description adds generic 'filtered, searched, sorted, and paged' claims but does not explain how search and sorting are controlled, especially since no such parameters exist in the schema. It does not contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with the verb and resource front-loaded and a compact tail describing capabilities. There is no filler, redundant restatement of the tool name, or extraneous detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a full input schema, output schema, and read-only/idempotent annotations, the description covers most of what an agent needs. The missing piece is clarity around the claimed 'searched, sorted' behavior, since an agent may look for search/sort parameters that are not present in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all six parameters, including the required schedule date window, pagination, and site_id default. The description adds no additional parameter-level meaning beyond high-level 'filtered, searched, sorted, and paged' phrasing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource ('equipment timeline entries (bookings)') and the intended view ('cockpit equipment list view'), distinguishing it from siblings like clm_list_equipment and clm_get_shipment_timeline. However, it also claims the tool supports 'searched, sorted' behavior, but no search or sort parameters exist in the schema, introducing slight imprecision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for the cockpit equipment list view' gives useful context, but the description does not state when to use this tool versus alternatives such as clm_list_equipment or clm_get_shipment_timeline. No explicit when-to-use or when-not-to-use guidance is provided; usage must be inferred from the name and sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint, covering the safety profile. The description adds the useful 'summaries' nuance, but does not go beyond annotations in disclosing behavior such as site defaulting or the literal-match status quirk, though those are covered in the schema. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler: verb, resource, scope, and filters are all present. Every word carries meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a complete input schema, annotations for read-only behavior, and an output schema, the description is largely sufficient for an agent to invoke the tool correctly. A small deduction is warranted because it does not signal when to choose this over the singular material handover tool, but that is not essential given the available structured context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all parameters. The main description adds no parameter-level meaning beyond what the schema provides, so the baseline of 3 applies even though the schema's status description is unusually detailed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List'), a clear resource ('material handover summaries'), and filters ('status and date range'). It is clear about what the tool does, though it does not explicitly differentiate itself from clm_get_material_handover or other list-style siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied by the description: use it to list material handover summaries for a site within a date range and status filter. However, it gives no explicit guidance on when to prefer this over clm_get_material_handover or when not to use it, and no alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds one behavioral fact beyond annotations: the comment is attributed to the current user. However, it does not disclose whether identifiers are validated, whether duplicate comments are possible, or any authentication/authorization requirements. destructiveHint=false only indicates the operation is not destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb and object, and no filler. It earns its place by adding attribution information beyond the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create-comment command with an output schema, the description covers the core operation and attribution. But it omits the logical relationship between ShipmentId and ItemId and gives no behavioral expectations beyond creation, leaving some ambiguity for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters, but it only generically names 'comment' and 'shipment'. ItemId remains entirely unexplained, and the description does not clarify which of ShipmentId or ItemId is logically required or how Comment should be formatted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('Adds a new comment') on a clear resource ('a shipment') and adds the useful attribution detail ('to the current user'). This distinguishes it from sibling comment tools like update_shipment_comment, delete_shipment_comment, and get_shipment_comments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the create scenario by using 'new comment', but it does not explicitly state when to prefer this over update_shipment_comment or delete_shipment_comment, nor mention prerequisites. Usage context is inferable but not explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the sparse annotation (destructiveHint: false), the description discloses meaningful behavioral side effects: creating/recreating a calendar reservation object, conditionally publishing an availability-set command, and queuing a background command for zone attachment refresh. This gives the agent a strong sense of what invoking the tool will actually do.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense sentence that front-loads the primary action and then conveys important side effects. It contains no filler, though the parenthetical side-effect chains make it somewhat heavy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex mutation command with a large undocumented parameter surface and only a destructiveHint annotation, the description covers the high-level flow but leaves critical gaps: no guidance on required fields, no identifier semantics, no explanation of bookable versus non-bookable behavior, and no clarification of update-versus-create selection logic.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the nested params object contains 30+ undocumented properties, yet the description names none of them. It does not explain which fields identify an existing record, which are needed for creation, or what concepts like BookableType, CapacitySchedule, or EquipmentPurposeLangKey mean.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Creates... or updates...') and a clear resource ('site equipment master record'), and adds side-effect detail that distinguishes it from related equipment commands like upsert_unplanned_equipment or update_equipment_status. The create/update branches are explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use it: when creating a new site equipment master record or updating an existing one. However, it does not explicitly mention alternatives, exclusions, or conditions that should route an agent to a different tool such as upsert_unplanned_equipment or update_equipment_status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only flag destructiveHint=true; the description adds substantial behavioral context: the operation marks rather than removes, the comment is excluded from subsequent reads, and physical data remains intact. This clarifies the partial-reversibility nature of the mutation. It does not disclose whether the deletion can be undone or the effect on related bookings, but the disclosure of soft-delete semantics notably exceeds the annotation baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single 22-word sentence that front-loads the core behavior ('Soft-deletes an equipment booking comment') before adding the subtle detail about read exclusion and physical retention. Every clause earns its place; no filler, no repetition of the tool name's obvious parts.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter mutation with only destructiveHint annotated, the description explains the behavioral consequence well and the output schema covers return values. However, it leaves the agent to guess what ItemId denotes and whether the soft-delete is reversible, and it does not reference the obvious counterpart clm_site_equipment_command_save_equipment_booking_comment. Adequate but with clear gaps around the parameter and lifecycle.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description says nothing about ItemId. The property name 'ItemId' is ambiguous — it could be an equipment item ID or the comment's own ID — and the description's 'equipment booking comment' reference only loosely implies the target. Furthermore, ItemId being nullable with a null default is a notable quirk that the description does not address. With zero schema coverage, the description was obliged to compensate and did not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('soft-deletes'), a precise resource ('equipment booking comment'), and the exact semantics (marked as deleted, excluded from reads, not physically removed). This distinguishes it from sibling hard-delete tools like clm_site_equipment_command_delete_equipment and clm_shipment_command_delete_shipment_comment, and the soft-delete qualifier adds meaning beyond the tool name's plain 'delete'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the operation's effect but gives no guidance on when to choose it over alternatives. With siblings clm_site_equipment_command_discard_equipment_booking, clm_site_equipment_command_save_equipment_booking_comment, and clm_shipment_command_delete_shipment_comment nearby, there is no mention of when this soft-delete is preferred, whether hard deletion is possible elsewhere, or whether a deleted comment can be restored.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare destructiveHint=false, so the description carries most of the behavioral burden. It does disclose that the filter is saved 'for the current user' and lists the filter criteria, but it does not disclose idempotency, overwrite behavior of an existing weekly filter, authentication requirements, failure modes, or what response is returned. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one compact sentence with no filler, and the most distinguishing feature ('weekly view') is front-loaded. Every clause adds relevant information about scope and filter criteria.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is an output schema but no detail about what the saved filter response contains, and the description does not explain relationships between FilterId, AppName, and the filter criteria. For a create-style tool with low schema coverage and a single params object, the description is adequate but not complete: it lacks guidance on required versus optional filter fields and default behaviors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so all parameter meaning must come from the description. The description maps the schema parameters reasonably: SiteId to 'site', SenderTeamIds/RecipientTeamIds to 'sender/recipient teams', MovingEquipmentIds/UnloadingEquipmentIds to 'moving/unloading equipment', HasIncidentAnnotation/HasDocumentationAnnotation to 'annotation flags'. It is less clear about FilterId, FilterName, and AppName, but the overall semantics are conveyed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Saves') and resource ('cockpit weekly filter'), and enumerates what the filter includes (site, sender/recipient teams, moving/unloading equipment and annotation flags). It clearly distinguishes this from the sibling clm_user_setting_command_delete_cockpit_weekly_filter, though it does not differentiate it from clm_user_setting_command_create_cockpit_equipment_filter by name, so it relies on the 'weekly' qualifier to differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for persisting a weekly-view filter for the current user, and the scope ('for the current user') gives some context. However, it provides no explicit when-to-use guidance, no exclusions, and does not mention alternatives such as the equipment-filter creation sibling or the delete-weekly-filter sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With destructiveHint=true, the destructive nature is already disclosed. The description adds useful ownership context ('belonging to the current user') and an existence precondition, but it does not disclose permanence or behavior when the FilterId does not exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is one front-loaded sentence with a clear action, resource, and scope. There is no filler or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter destructive command, the description is nearly sufficient and the output schema covers return values. It remains incomplete on parameter semantics, null/default behavior, and explicit routing to the analogous weekly-filter deletion tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must clarify FilterId, but it never names it or explains how to identify the filter. The schema shows a nullable FilterId with a default of null, and the description does not address what happens when it is omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete verb ('Removes'), a specific resource ('"equipment view" cockpit filter'), and a scope ('current user'). This clearly distinguishes it from sibling tools such as delete_cockpit_weekly_filter, which act on a different filter type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The use case is implied: use this when deleting an equipment-view cockpit filter for the signed-in user. However, it never explicitly contrasts with the weekly-filter sibling or describes when not to use it, so an agent must infer the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation already labels this as destructive, and the description confirms the deletion behavior. It adds useful context about user scoping ('belonging to the current user') but does not disclose consequences such as permanence or what happens if the filter does not exist. With the annotation covering the main safety signal, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the action and object. There is no redundant phrasing or irrelevant detail; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core operation, and an output schema exists, so return values need no explanation. However, the lack of any parameter guidance and the absence of usage context beyond the basic delete action leave meaningful gaps for a command with a single, undocumented parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention the FilterId parameter at all. An agent must rely solely on the parameter name to infer that FilterId identifies the filter to delete, with no guidance on how to obtain the value or that null is allowed by default. The description fails to compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Removes') with a clear resource ('weekly view cockpit filter') and scope ('belonging to the current user'). It distinguishes this from sibling tools like the equipment filter delete because it explicitly names the 'weekly view' target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose is clear enough to imply when to use it: when deleting a weekly view cockpit filter for the current user. However, the description does not explicitly mention alternatives or conditions such as 'use create_cockpit_weekly_filter to add a filter,' so the usage guidance remains implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the minimal annotations, the description discloses two meaningful behaviors: params are validated against the operation's resolved schema before the HTTP call, and *Command writes are refused when CLM_ENABLE_WRITES=false. This gives the agent important runtime expectations, though it does not cover error output or side-effect details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, followed by two high-value behavioral notes. There is no fluff or repetition; every sentence adds necessary context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main operational needs: where operations come from, how params are validated, and the write-refusal condition. It does not mention how to retrieve the resolved schema or what the response format looks like, but for a generic invocation tool these are reasonable gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining both parameters: operation must be an operation listed by clm_list_operations, and params is a payload validated against that operation's resolved schema. It does not enumerate dynamic fields, which is appropriate for a generic dispatcher.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: it executes any operation exposed through clm_list_operations, establishing this as a generic dispatcher. It stops short of a 5 because it does not contrast itself with the many dedicated sibling command tools in the list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to choose clm_invoke over the many dedicated sibling operation tools. The description says 'any operation' but does not mention preferring specific tools or using this only for operations not already exposed as dedicated functions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide destructiveHint=true and idempotentHint=false, and the description adds meaningful behavioral context beyond them: it discloses team assignment, automatic status computation, access-control role setup, and queued background jobs to refresh site-structure and team grouping counts. These are non-obvious side effects an agent could not infer from the annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with minimal waste, front-loaded with the primary create action before the secondary details. The first sentence is dense (four behaviors in one sentence) but every clause earns its place, and the second sentence usefully flags the background-job side effect.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's procedural behavior and side effects well, and since an output schema exists, explaining return values is unnecessary. However, for a create command with 26 optional-looking parameters, it is incomplete: an agent cannot determine what a minimal valid call looks like, how fields group together, or what the computed 'initial status' and access-control roles actually are.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description bears the full burden of explaining parameters. It conceptually maps a few fields (sender/recipient team, project/site, status), but 26 nested properties remain undocumented — with no guidance on which fields are required for a valid creation, how they relate to each other, or what the date/numeric fields mean.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource — 'Creates a new lean card (working package)' — and clarifies the domain term 'lean card' by equating it with 'working package'. It then enumerates what the create encompasses (sender/recipient team assignment, initial status computation, access-control roles), which cleanly distinguishes it from the sibling lean_card_update tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: an agent can infer this tool is for creating a new working package, as opposed to updating one or creating a lean document. However, there is no explicit 'use this when' / 'use that instead' guidance, no exclusions, and no mention of prerequisites before creating a lean card.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses useful behavioral traits beyond the annotations: the operation is queued/background, creates a temporary upload record, and notifies the uploading user. However, the annotations mark destructiveHint=true, and the description does not explain what destructive action occurs (e.g., replacing a previous upload record), leaving an important ambiguity for a mutation command.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one dense sentence but contains only relevant information: what is queued, what processing does, notification behavior, and the follow-up step. It is front-loaded with the core action and wastes no words, though its long clause chain could be split for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the operation's purpose, async nature, and place in the workflow, and an output schema exists so return-value documentation is not required. However, it leaves SiteId unexplained and does not clarify the destructive side effect indicated by the annotation, so the overall picture is incomplete for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only indirectly hints at FileId ('uploaded working-package Excel file') and SheetName ('selected sheet'). SiteId is not mentioned at all, and no parameter is explicitly mapped or explained. This is insufficient for an agent to confidently populate all three fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Queues') and names the exact resource ('initial background processing of an uploaded working-package Excel file'), then expands with concrete steps: reading the selected sheet, parsing rows/columns into a temporary upload record, and notifying the user. It also differentiates this from later steps by mentioning 'in preparation for the header-mapping step,' which distinguishes it from sibling header-mapping tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'initial background processing' and 'in preparation for the header-mapping step' clearly place this tool at the start of the upload workflow. It does not explicitly name alternative tools or say when not to use it, but the workflow context is strong enough for an agent to infer it should be called before header mapping, not after.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (idempotentHint=false, destructiveHint=true), the description adds genuinely useful behavioral context: the operation is queued for background processing rather than synchronous, and the requesting user receives a notification upon completion. It does not clarify what the destructiveHint refers to (e.g., overwriting an existing report file at the same PdfName or storage ID), which prevents a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single 25-word sentence with the core action front-loaded ('Queues generation of the cockpit daily report PDF'), followed by content scope and then the async/notification behavior. Every clause earns its place; there is no filler or repetition of schema or annotation data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
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 described), the tool has 11 opaque parameters at 0% description coverage and a destructiveHint=true side-effect flag, yet the description addresses neither parameter semantics nor what the destructive behavior impacts. For a command with this complexity, the high-level purpose alone is insufficient 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.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it explains none of the 11 parameters (FileId, PdfName, Language, RaiseEvent, FooterHeight, HeaderHeight, MetaDataList, PdfStorageId, RaiseNotification, TemplateStorageId, PdfGenerationProfileId, PageNumberHorizontalAlign). An agent has no guidance on what these control or which, if any, are needed for a sensible default invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb+resource: 'Queues generation of the cockpit daily report PDF' with an explicit content scope (scheduled shipments, equipment, ad-hoc shipment summaries). This clearly differentiates it from sibling clm_shipment_command_generate_shipment_pdf and the timeline Excel report tools, since the report type and subject matter are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: call this when you need the cockpit daily report generated in the background. However, there is no explicit when-to-use/when-not-to-use guidance, no mention of alternatives, and no statement about prerequisites (e.g., whether a template or generation profile must already exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false. The description adds useful behavioral context beyond annotations: upsert semantics and the fact that a background command is queued to finish processing, such as thumbnail generation and notifications. This is meaningful additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence that conveys the core operation, the scoping to ad-hoc shipments, and the background side effects. The parenthetical examples are useful and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the large parameter surface, 0% schema description coverage, and no parameter-level guidance, the description is not sufficient for confident invocation. It does not clarify what identifiers are expected or how the params object should be populated. The output schema reduces the need to explain return values, but the input structure remains under-described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no parameter-level meaning. The mention of a 'given ID' is confusing because the input schema does not surface an explicit shipment ID field, and the many nested optional fields remain unexplained. The description does not compensate for the schema coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Creates or updates an ad-hoc (walk-in, non-wizard) shipment'. It clearly explains the conditional behavior (update if the ID exists, otherwise create) and distinguishes this tool from wizard-based shipment commands in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description scopes the tool to ad-hoc, walk-in, non-wizard shipments, which differentiates it from the save_shipment_wizard_* sibling commands. It gives clear context on when this tool applies, though it does not explicitly name alternative tools or state a when-not-to-use condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only flag destructiveHint=false, so the description adds value by clarifying that this is a persistent, user-scoped creation operation. It does not discuss idempotency, duplicates, prerequisites, or side effects, but for a simple create command this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence front-loads the verb and resource while parenthetically enumerating the criteria. There is no wasted wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested params object and nine properties, a single sentence is thin: it captures the core purpose but not the remaining optional parameters or the criteria for choosing this over the weekly-filter sibling. The output schema and destructiveHint reduce the burden for return behavior and safety.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It translates SiteId, RecipientTeamIds, BookableEquipmentIds, NonBookableEquipmentIds, and the annotation flags into readable terms, but it omits AppName, FilterId, and FilterName, and does not explain the params wrapper.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Saves a new'), a specific resource ('equipment view cockpit filter'), and a clear scope ('for the current user'). The 'equipment view' qualifier distinguishes it from the sibling weekly-filter creation tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'new' implies this tool is for creation rather than deletion or update, and 'equipment view' separates it from create_cockpit_weekly_filter. However, there is no explicit when-to-use/when-not-to-use guidance or mention of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds useful grouping context by status bucket, but does not disclose additional behavioral details such as date-window semantics or defaulting behavior, though the schema covers those.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence with no filler. It front-loads the core action and includes the key status breakdown immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only count tool with full parameter schema and output schema available, the description is mostly sufficient. It could be more complete by explicitly guiding the agent toward or away from sibling shipment tools, but that is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema clearly documents site_id and the inclusive schedule date parameters. The description does not add extra meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool provides shipment counts for a site, grouped by status bucket. This distinguishes it from sibling list/search/get tools by emphasizing aggregate counts rather than individual records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for obtaining count summaries by status, but it does not explicitly state when to use it instead of related tools like clm_list_shipments, clm_search_shipments, or clm_get_shipment_summary. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to repeat safety traits. It adds useful context that the result is 'smaller' and 'external-facing', but it does not disclose failure behavior, id-type nuances, or any integration-specific differences beyond the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly worded sentence that front-loads the action and object. Every phrase adds value: 'smaller', 'external-facing', and 'native CLM or KonsHub-linked' all carry meaning without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only lookup with one fully documented parameter and an output schema, the description is largely sufficient. The main gap is the lack of explicit guidance on when to choose this over clm_get_shipment or other shipment detail tools, plus no elaboration on what 'KonsHub-linked' changes in practice.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage: shipment_id is required and described as 'The shipment's id.' The description adds no additional meaning about id format, whether it is a CLM id or an external/KonsHub id, or any constraints. This matches the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Retrieve'), a specific resource ('a shipment's smaller, external-facing summary'), and even distinguishes two supported variants ('native CLM or KonsHub-linked'). This differentiates it from siblings like clm_get_shipment and other shipment-detail tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'smaller, external-facing summary' implies it should be used when a concise, externally shareable snapshot is needed rather than full shipment details. However, it never explicitly names alternatives like clm_get_shipment or states when not to use it, leaving usage selection partly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds site-scoping and status-filter context, but does not disclose pagination behavior, default site fallback, or any other traits beyond what the schema already states.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It states the verb, resource, scope, and filter efficiently while leaving detailed parameter semantics to the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is mostly complete given the rich schema (100% coverage), output schema, and safety annotations. It lacks only explicit guidance about status value sources or related count/list alternatives, though those are partially covered by sibling names and schema references.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the structured schema already documents all five parameters. The description only mentions 'status' and 'site' in general terms and adds no meaning beyond the parameter descriptions already present.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb 'List', names the resource ('lean cards (working packages)'), and adds scope ('for a site') and filter ('by status'). It clearly distinguishes the operation from counting or command-oriented siblings like clm_count_working_packages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case — listing working packages filtered by status — but it does not explicitly say when to prefer this over alternatives such as clm_count_working_packages or clm_list_enums. No exclusion or alternative-routing guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, and the description's 'Retrieve' is consistent with those. The description adds no additional behavioral context such as data scope, auth, or side effects, but none are needed given 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence communicates the operation, resource, and cardinality with no filler or redundancy. It is appropriately front-loaded and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only lookup with one fully documented required parameter, an output schema, and read-only/idempotent annotations, the description is complete enough for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: item_id is described as 'The incident's item id.' The description adds no further parameter-level meaning, so the schema-supported baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Retrieve'), a specific resource ('incident/finding'), and a scope ('single', 'full detail'), which clearly distinguishes it from sibling tools like clm_list_incidents and the incident command tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The singular scope implies this is for retrieving one incident by ID, but it never explicitly states when to choose this over clm_list_incidents or other incident-related siblings. No exclusions or alternative routing are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, and the description does not contradict them. It adds useful scope by noting the response includes event history and equipment usage, but it does not disclose additional behavioral traits such as error handling or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It conveys the resource, granularity, and key content areas efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple one-parameter getter backed by an output schema and read-only/idempotent annotations. The description offers enough context about what the tool returns, and nothing essential for invoking it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already explains handover_id as 'The material handover's id.' The description adds no parameter-level meaning beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource as a single material handover and states that it returns full details, including event history and equipment usage. The word 'single' distinguishes it from sibling list tools like clm_list_material_handovers, and the read-only intent is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for fetching details about one specific handover as opposed to listing handovers, but it does not explicitly say when to prefer it over alternatives or provide exclusions. There are no sibling routing hints such as 'use list_material_handovers to find IDs first.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered without the description. The description adds the behavioral context that the response includes commenter display info, but it discloses no ordering, pagination, or scoping details beyond 'all comments.' No contradiction with the read-only annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero filler. The verb and resource appear first, and 'with commenter display info' earns its place by adding output context. Nothing could be trimmed without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with 100% schema coverage, read-only annotations, and an output schema present, the description covers the essentials. The 'all comments' scoping statement adds useful behavioral context, and nothing critical for invoking the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so shipment_id is already documented as 'The shipment's id.' The description's 'on a shipment' phrasing loosely reinforces the parameter's role but adds no format, syntax, or semantic detail beyond the schema. Baseline 3 applies when the schema carries the weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a precise resource ('comments posted on a shipment'), and adds a useful output detail ('with commenter display info'). This distinguishes it from sibling comment mutation tools (create/update/delete_shipment_comment) and other shipment read tools like clm_get_shipment_event_logs and clm_get_shipment_timeline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied by the verb 'List' and the readOnly annotation, but the description never explicitly states when to choose this over alternatives such as clm_shipment_command_create_shipment_comment or clm_get_shipment_event_logs. No when-to-use or exclusion guidance is provided; an agent must infer the use case from the name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so no safety contradiction exists. The description adds meaningful behavioral context beyond those annotations: output is a chronological history and the accepted entity can be a shipment or a related connected entity. This is useful but does not go into deeper operational details like pagination or filtering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It conveys the action, the resource, the entity scope, and the ordering in under twenty words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only tool with an output schema, the description covers the essential contextual facts: what is retrieved, for which entity types, and in what order. The output schema can carry return-value details, and annotations cover idempotence and read-only safety.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the item_id parameter is already described as 'The shipment (or related entity) id, as a UUID.' The tool description largely repeats this same scope ('shipment or related connected entity') and adds no new format, constraints, or usage semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Retrieve' with the resource 'audit/event log history', and adds the ordering trait 'ordered chronologically'. It is clear what the tool returns, though it does not explicitly differentiate itself from similar sibling tools like clm_get_shipment_timeline or clm_get_shipment_comments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is appropriate when audit/event log history is needed and notes it applies to 'a shipment or related connected entity'. However, it provides no explicit when-to-use or when-not-to-use guidance and names no alternative sibling tools, leaving selection vs similar getters to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits beyond the annotations: it only registers the document if it does not already exist, queues asynchronous background processing, and ultimately creates or updates lean cards. This is helpful transparency for a command-like tool, though it does not cover failure modes or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action and then explains the workflow. It avoids unnecessary filler, though it is somewhat dense with clauses.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description conveys the tool's purpose and async behavior well, and an output schema exists so return-value details are not required. However, the absence of any parameter-level guidance and lack of stated prerequisites—such as how the document upload happens or which identifiers are needed—leave the agent with meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and all five parameters have no descriptions. The high-level description mentions project/site and an uploaded Excel workbook, but it does not clarify the roles of FileId, ItemId, SiteId, FileName, and ProjectId, leaving parameter selection ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: registering an uploaded Excel workbook for bulk import/refresh of lean cards, then queueing background processing. It distinguishes itself from sibling lean-card commands by describing the bulk-import workflow rather than direct single-card creation or update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for bulk importing or refreshing lean cards from an uploaded Excel workbook. It does not explicitly name alternatives or state when not to use it, but the scenario is specific enough for an agent to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses meaningful side effects: status recalculation and queued background jobs to re-sync site-structure and team grouping counts using old and new values. The destructiveHint and idempotentHint annotations are not contradicted; the description adds behavioral context the annotations 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that front-loads the action and resource, then lists the affected fields and side effects in a logical order. Every part adds value, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description captures key side effects and the main field scope, but it leaves important operational details unstated, such as which parameter identifies the target lean card and how partial updates behave when most parameters are null/default. Since an output schema exists, return-value details are not needed, but the missing identifier guidance is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description partially compensates by naming most updatable fields and grouping them semantically (location, dates). However, it omits ItemId, which is the likely identifier for selecting which lean card to update, and it does not clarify the behavior of omitted/null fields or whether all properties are optional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Updates'), identifies a specific resource ('existing lean card'), and enumerates the affected fields (location, comment, dates, archived flag, volume, transport unit). This clearly distinguishes it from sibling create/delete tools and makes 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for modifying an existing lean card, which is clear from the wording, but it does not explicitly contrast with sibling tools like clm_lean_card_command_lean_card_create or state when not to use it. No prerequisites or exclusions are provided, leaving usage guidance to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, so the description is not burdened with stating that this is a side-effecting operation. It adds useful behavioral context beyond annotations: the email is localized to each recipient's preferred language and is sent specifically to the sender team, not all members. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler. The main action ('Sends an email notification') is front-loaded, followed by recipient targeting and the notification reason. Every clause adds relevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the presence of an output schema, the description is incomplete for a 4-parameter side-effecting tool. It does not explain what each parameter means, whether the working package must already be updated with new dates, or whether the email is the only effect. An agent would need to open the schema and infer param semantics from names alone, which is risky with 0% schema description coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden of explaining the parameters. It does not mention Message, OldEndDate, OldStartDate, or WorkingPackageId at all. While the overall purpose lets an agent infer that WorkingPackageId identifies the working package and Old* fields are the previous dates, the tool name and description do not explicitly clarify parameter roles or relationships.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Sends an email notification'), identifies the resource ('lean card's (working package's) sender team'), and states the exact purpose (informing about changed start/end dates). It is clearly distinguishable from sibling send-email tools like clm_shipment_command_send_open_shipment_mail or clm_site_equipment_command_send_open_equipment_booking_mail due to the domain and target audience.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys clear usage context: it should be used when a working package's dates have changed, to notify the sender team. It does not explicitly name alternatives or state when not to use it, but the domain-specific trigger is evident enough for an agent to select it over unrelated email-sending siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already flag destructiveHint=true and idempotentHint=false, the description adds substantial behavioral context not visible anywhere else: the appended completion event, the parent-shipment status aggregation with conditional PDF regeneration, the background thumbnail job, and the time computation from paired events. Nothing in the description contradicts the destructive annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The main action is front-loaded and every clause contributes distinct information, so there is no waste. However, the entire description is one dense run-on sentence packing six side effects into comma-separated clauses; splitting it into a purpose statement plus a side-effect list would improve scannability without adding length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description thoroughly covers the tool's side effects, and since an output schema exists it need not explain return values. However, it assumes domain knowledge such as 'paired handover events' and completion-type semantics, and it does not state preconditions or what happens if the handover is already completed, which matters for a non-idempotent destructive command.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only gives meaning to the photos and note parameters. ItemId, CompletionType (a bare integer with no enum or hinted meaning), and CompletedByUserId are never explained, and the QR-code responsible-person clause does not clearly map to any schema property. For an agent, the majority of parameters remain ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and outcome ('Marks a handover as Completed') and enumerates concrete effects: appending a completion event, storing photos/note, computing total time, updating the parent shipment, triggering PDF regeneration, and queuing thumbnail generation. This makes the tool's role unmistakable and clearly distinguishes it from siblings like change_material_handover_status or create_material_handover.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (finalizing a handover with photos, note, and time computation) but never explicitly states it, and it does not route the agent away from the closely related sibling clm_material_handover_command_change_material_handover_status. Preconditions such as the handover's required current status or whether the handover can be re-completed are also absent, leaving the agent to infer selection criteria from the behavior list alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations carry only destructiveHint=false, so the description must disclose behavior — and it does so richly: it snapshots the shipment's bookable equipment, consumes a sequential handover number, mutates the shipment's aggregated status/counters on a different entity, and queues an asynchronous background job. These side effects are not derivable from the annotations and materially help an agent predict consequences. No contradiction with destructiveHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded and every clause earns its place, since each names a real side effect (snapshot, sequential number, counter/status update, thumbnail job). It is one dense, run-on sentence that would read better split into two, but there is no wasted wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Behavioral coverage is strong and the output schema presumably covers return values, but the tool has 8 undocumented parameters and only a minimal annotation set. The description omits parameter meanings and any prerequisites (e.g., required shipment state), leaving an agent unable to construct valid input reliably. Behavior is complete; invocation inputs are not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description bears the burden of explaining parameters — and it largely fails. None of the eight nested params (Note, Type, Floor, ItemId, Building, ShipmentId, LaydownArea, MaterialPhotos) are defined; the narrative only alludes to 'shipment' (ShipmentId) and 'material photos' (MaterialPhotos), leaving Type/Floor/Building/LaydownArea/ItemId semantics and formats completely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Creates a new material handover for a CLM or Konshub shipment.' It then enumerates the full creation behavior — snapshotting bookable equipment, assigning a sequential handover number, updating aggregated status/counters, and queueing a thumbnail job — which clearly separates it from sibling operations like complete_material_handover or change_material_handover_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: an agent can infer 'use this when creating a new handover' from the verb 'Creates' and the resource scope 'for a CLM or Konshub shipment.' However, the description never explicitly names alternatives (complete, change status, update planned equipment usage) or states when not to use this tool, leaving routing to inference among closely related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (idempotent, non-destructive), the description discloses a critical behavioral trait: changes apply directly for in-creation shipments, but become a pending draft for already-submitted shipments. This is exactly the kind of state-dependent behavior an agent must know before invoking the tool. It adds meaningful transparency without contradicting 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and reasonably concise, front-loading the main action before explaining the two modes. The semicolon-separated conditional structure is somewhat dense but every clause earns its place. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 10 undocumented optional fields and an output schema, the description covers the core behavior but leaves substantial parameter meaning unexplained. An agent could correctly identify the tool but would struggle to populate fields beyond Materials and RecipientTeamId/Name correctly. The state-dependent behavior is well covered, but the parameter gap makes the definition only partially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the params object contains 10 distinct fields, yet the description only mentions materials and recipient team. It does not explain the meaning, format, or purpose of fields like CommissionedId, LaydownArea, BookingDate, Floor, Building, or MaterialComment. Since the schema provides no descriptions, the description should compensate more heavily but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: 'saves the material-selection step of the shipment wizard.' It also clarifies the scope by mentioning materials and recipient team, which distinguishes this from sibling tools like booking-dates, timeslots, and unloadings wizard steps. The state distinction (new shipment vs. submitted shipment) further sharpens what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly identifies the context: use this when saving the material-selection step of a shipment wizard. It explains behavior for both creation and editing scenarios, giving the agent a good sense of when it applies. It does not explicitly name alternatives or exclusions, such as the smart-shipment material sibling, but the context is clear enough for a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable non-obvious behavior: edits to already-submitted shipments are stored as a pending draft rather than directly applied, while in-creation shipments are updated immediately. This is exactly the kind of behavioral context that helps an agent reason about consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence but is efficiently front-loaded with the tool's purpose, followed by the two behavioral modes. There is no filler or repetition. It could be split into shorter sentences for readability, but it earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description clearly explains the tool's role and key behavioral distinction, and an output schema exists to describe returns. However, with 0% schema coverage, the omission of ShipmentId and BookingDate semantics leaves the calling contract incomplete. An agent would likely need additional inference to know how to populate those parameters correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. It explains what the Vehicle object conceptually contains (name, type, ID, key), but it does not mention ShipmentId or BookingDate at all. With three meaningful parameters and no schema descriptions, this is a significant gap for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Saves the unloading/vehicle step of the shipment wizard.' It further clarifies exactly which data is affected (vehicle name, type, ID, key) and distinguishes the two shipment states. This clearly separates it from sibling wizard-step tools like save_shipment_wizard_material or save_shipment_wizard_timeslots.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear contextual guidance: use it when saving the unloading/vehicle step, whether for an in-progress shipment or an already-submitted shipment being edited. It does not explicitly name sibling alternatives or provide exclusion criteria, but the context is strong enough for an agent to select this tool over other wizard steps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false. The description goes beyond that by disclosing that the aggregate record is persisted, that it is recomputed from open and approved shipments/bookings, and—critically—that the record is removed when total usage becomes zero. This deletion behavior is exactly the kind of side effect an agent needs to know about and is not visible in the annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence front-loads the action and resource, then packs the computation rule and the zero-usage deletion side effect without wasted words. It is slightly long-winded with stacked clauses, but every clause carries meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the input is just two optional/nullable parameters, the description covers the core computation, the persistence aspect, and the destructive edge case. It does not state permission requirements, but the destructiveHint annotation covers the main risk. It is nearly complete for a command of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does identify BookingDate as the operative date for the aggregate. However, it only implicitly covers SiteEquipmentId as 'site equipment' in the text; neither parameter's format, optionality, or effect is explicitly explained. The description adds meaning but leaves modest gaps for a two-property input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Recalculates and persists') plus a clear resource ('bookable site equipment's daily usage aggregate') and a date parameter. It also states the computation inputs (open and approved shipments/bookings against total available time) and the default behavior when usage is zero (aggregate removed), which makes it fully distinguishable from the large sibling set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the use case: recalculating a single equipment's daily usage aggregate after relevant changes. However, it never explicitly says when to call this versus the other site-equipment commands or whether it is intended as a maintenance/background command rather than a user-facing action. No alternatives or exclusions are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses more than the annotations alone: it notes that the tool queues a background command that finalizes the booking via timeline creation and approval notifications. This gives the agent a meaningful picture of side effects, though it does not cover failure behavior or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that front-loads the core action and then adds relevant detail. It is not overly verbose, though the long parenthetical list makes it slightly harder to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 16-field creation tool with zero parameter descriptions, the description gives a solid high-level overview and a useful lifecycle explanation, but it is not complete enough to fully guide correct invocation. The agent still must infer the meaning of many parameters and the exact relationship to sibling save/update commands.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only provides broad groupings like 'booking date/slots, transport info, and other info'. It does not explain ambiguous fields such as ItemId, EquipmentId, Building, Floor, RecipientClmTeamId, or TimeZoneOffset, leaving significant semantic gaps for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new site equipment booking from mobile in a single call, explicitly distinguishing it from the sibling update_equipment_booking_from_mobile and the partial save_* commands. It names the resource, the action, and the overall scope, so an agent can immediately understand what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'submitted from the mobile app in a single call' gives clear context for when this tool is appropriate, especially against sibling partial-save commands. However, it does not explicitly name alternatives or state when not to use this tool, so some routing inference is still required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotence and non-destructive behavior, so the description only needs to add extra behavioral context; it adds the draft-vs-record target and step semantics, which is useful but not extensive. It does not describe effects on existing data, validation, or prerequisites, but nothing contradicts 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence front-loads the action and target, then packs the relevant field list into a parenthetical. Nothing is redundant or overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a save step in a crowded wizard-tool family, the description identifies the right step and most fields, and an output schema exists to cover return values. It is incomplete because ItemId is not explained and there is no guidance on what must be present or how this step interacts with the booking draft lifecycle.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate, and it does translate most properties into plain terms: building/floor, transport unit quantity, recipient team, material comment, and price per unit. However, ItemId is absent from the description and the schema provides no help, leaving a key identifier parameter unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('saves'), a specific resource ('site equipment booking'), and the exact step ('transport-info'), distinguishing it from sibling save steps like save_site_equipment_booking_info and save_site_equipment_other_info. Listing the contained fields removes ambiguity about which data belongs here.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly frames the tool as one step of a site equipment booking flow and mentions it can apply to the booking record or its draft, which is enough context to know when it is relevant. It does not explicitly name alternatives or state when not to use it, but the step scoping 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral detail beyond the annotations: the operation is asynchronous, returns immediately, and does not produce the result synchronously. The annotations only indicate non-idempotent and destructive hint, so this extra context is meaningful. It does not explain how the completed report is delivered, but the async behavior is the key disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single information-dense sentence that front-loads the core behavior and asynchronous nature before listing filters. Every part adds relevant information, though the sentence is somewhat long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately captures the main behavior and primary filter dimensions, and an output schema is available to describe return values. However, with about 16 optional parameters and 0% schema description coverage, several parameters remain undocumented, leaving clear gaps for an agent that needs to configure the report precisely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only names a subset of the params: site, status, schedule date range, and sender/recipient teams. Many important parameters remain unexplained, such as FileId, Language, Ascending, OrderByField, SearchKeys, ShipmentIds, ShipmentTypes, equipment IDs, and annotation flags. With zero schema-level descriptions, the tool description should have compensated much more fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it queues an asynchronous request to build an Excel export of the shipment list view (UP timeline), and lists the relevant filters. The 'UP timeline' qualifier distinctively differentiates it from the similar sibling clm_timeline_command_generate_equipment_timeline_excel_report.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys when to use it: when an Excel export of the UP timeline is needed, and it clarifies that the call returns immediately rather than waiting for the file. It does not explicitly name alternative tools or exclusion conditions, but the resource scope and async behavior provide sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds behavioral context beyond annotations by specifying the status breakdown and the scope of the count. It does not mention edge cases like archived cards, but for a read-only count this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise, front-loaded sentence with no filler. It states the resource, the scope, and the breakdown in a compact form.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, one optional parameter with a clear schema description, and an output schema, the description is nearly complete. It could be improved with explicit guidance on when to use the count versus list variants, but nothing critical is missing for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full coverage for the single optional parameter, including its default behavior. The description merely references 'for a site' and adds no new parameter-level detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the function: counting lean cards (working packages) for a site. It also communicates the aggregation by status (overdue, active, pending, completed), which differentiates it from list-type and shipment-count sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for site-level working package counts, but it does not explicitly say when to prefer this over clm_list_working_packages or clm_count_shipments. No exclusions or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only and idempotent; the description adds useful behavioral detail by explaining that it returns resolved schemas, varies by POST vs GET, and includes response shape. It does not contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence front-loads the purpose and explains the output without filler. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only tool with an output schema, much of the context is present: purpose, output contents, and POST/GET distinction. However, the absence of any guidance on the `operation` value format leaves a real gap in the overall description, even considering the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain the `operation` parameter, but it only says 'one operation' and never states whether to pass an operation ID, name, or path, nor where to obtain it (e.g., from clm_list_operations). An agent cannot reliably know what string to provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and object, 'Describe one operation', and immediately specifies what is returned: resolved JSON Schema request body/query parameters and response shape. This clearly distinguishes the tool from sibling list/action tools by centering on introspection for a single operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'everything needed to build valid `clm_invoke` params' provides clear context for when to use this tool: before invoking an operation. It does not explicitly name alternatives or exclusion cases, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare idempotentHint true and destructiveHint false. The description goes beyond this by explaining that the operation not only updates usage but also recalculates the item's actual total price and propagates aggregated usage/price back into the shipment's equipment timeline. It also discloses that the usage unit may be unit count or time slots depending on price type, which is meaningful 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence delivers the core operation, the conditionality on price type, and the downstream effects without redundancy. It is front-loaded with the primary verb and resource, and every clause adds information. The length is appropriate for the complexity of the operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a command with an output schema and idempotent/non-destructive annotations, the description is largely complete: it explains what is updated, how the value is interpreted, and what side-effect cascades occur. It does not mention how to obtain ItemId or EquipmentId, but that is a minor gap against the tool's narrow scope. Overall, an agent has enough context to invoke it mostly correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does clarify the UpdatedUsage parameter's meaning (unit count or number of time slots depending on price type), but it does not explicitly define ItemId and EquipmentId or how they relate to the handover. The IDs are left to inference from names and domain knowledge, which is a noticeable gap given the complete absence of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (records actual usage), the target resource (a single planned/bookable equipment item on a handover), and the consequential effects (recalculating actual total price and rolling up into the shipment's equipment timeline). It also notes the price-type dependency, which further clarifies the operation. The 'on a handover' scope distinguishes it from site-equipment-level siblings even without naming them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when actual usage for a planned/bookable equipment item on a handover needs to be recorded. However, it does not state when not to use it, nor does it explicitly contrast it with alternatives like clm_site_equipment_command_calculate_bookable_equipment_usage or other material handover commands. This leaves the agent to infer the appropriate selection from the domain context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses key behavioral traits: if the PDF is not yet generated, it queues background generation and returns immediately without a URL. This async side-effect and immediate-return behavior is valuable context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the core behavior and then explains the important conditional case. No filler or redundant information is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The asynchronous behavior and conditional return are well covered, and an output schema exists, reducing the need to describe return values. However, the description leaves several optional parameters unexplained, and with 0% schema coverage, an agent may not know how to correctly set PdfId, IsGenerateFull, or UseImpersonation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden of explaining parameters. It only implicitly covers Language and ShipmentId via 'given language' and 'shipment'. It does not explain PdfId, IsGenerateFull, or UseImpersonation, leaving most parameters semantically undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: requesting and returning a generated PDF report for a shipment, with language-specific output. It also describes the conditional async queueing behavior. This distinguishes it from sibling report generators like cockpit or timeline reports by focusing on shipment PDFs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the conditional behavior: whether a PDF is already generated or needs to be queued. However, it does not explicitly state when to prefer this tool over alternatives, nor does it mention any exclusions or prerequisite conditions such as requiring a ShipmentId or PdfId.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark a non-idempotent, destructive side effect; the description adds context by stating the work is queued as a background job, targets the recipient, sends the email in every supported language, and depends on the shipment being found. This is meaningful behavioral disclosure beyond 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that immediately conveys the action and resource. It is slightly redundant ('notify...that a shipment has been requested' and 'sending the shipment requested email') and packs in the multi-language detail, but remains compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter command with an output schema and safety annotations, the description covers the key operational facts: asynchronous execution, recipient, email type, language scope, and the 'shipment found' trigger. The missing param semantics is already penalized separately; overall the context is serviceable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, and the description never names ShipmentId or explains the null default. The only implicit signal is that 'the shipment' refers to the parameter, so an agent gets little help beyond the parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('queues a background job to notify'), a clear resource (the shipment's recipient, the shipment requested), and the concrete email behavior. It is easy to distinguish from sibling commands such as clm_site_equipment_command_send_open_equipment_booking_mail because the resource and email type are explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The condition for use is explicit: the tool is for notifying a shipment recipient that a shipment has been requested, and it waits for the shipment to be found. It does not name alternatives or exclusions, so it stops short of a 5, but the intended context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the annotations: it re-validates and re-creates the calendar slot reservation, queues a background command, updates the timeline, and sends notifications. The annotations already cover idempotency and non-destructiveness, so the description appropriately focuses on additional side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence packs in the primary action, the re-validation/re-creation behavior, the background queue, and the notification side effect. There is no filler or repetition beyond a minor echo of 'from the mobile app' from the tool name, but overall it is tightly written.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is strong on overall behavior and side effects, but weak on parameter semantics and does not guide the agent toward this tool versus the many similar site-equipment sibling tools. The output schema presumably covers return values, so that gap is acceptable, but the missing parameter explanations and usage routing leave it only adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only hints at broad categories like 'booking/transport/other info' and 'calendar slot reservation'. It does not explain the purpose or format of the many parameters inside the params object, such as PricePerCountNoOfUnit, TransportUnitQuantity, or OnSiteResponsiblePerson.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Updates') with a specific resource ('an existing site equipment booking') and a clear scope ('booking/transport/other info'). It also distinguishes itself from creation tools by emphasizing 'existing', 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this when updating an existing site equipment booking from the mobile app. It does not explicitly name alternatives or state when-not-to-use, but the 'existing' qualifier and 'from the mobile app' context imply the right scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the behavioral effect (toggling the Active flag) beyond what annotations provide. Annotations already indicate idempotent and non-destructive behavior, and the description adds the specific state-change semantics without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise, front-loaded sentence with no filler. Every word contributes to understanding the tool's core behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and has an output schema, so return value documentation is not needed. However, the missing `ItemId` guidance and lack of explicit usage boundaries leave some ambiguity for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the parameters. It explains the meaning of `Active` but does not mention `ItemId`, which is essential for identifying the equipment record to update. This leaves a significant parameter gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Activates or deactivates'), a clear resource ('existing site equipment record'), and a concrete mechanism ('toggling its `Active` flag'). This distinguishes it from sibling tools like create/delete equipment operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies it is for changing the active status of an already-existing equipment record, which sets context against creation/deletion tools. However, it does not explicitly name alternatives or state 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide idempotentHint and destructiveHint, so the description carries important behavioral disclosure. It explicitly reveals timeline updates, queued background commands, actual usage/price calculation, slot freeing, and notification emails, giving the agent a clear model of side effects without contradicting 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that front-loads the core transition and packs status examples and side effects into one clause. It contains no filler, though the nested 'either...or' structure makes the background-command behavior slightly harder to parse than separate sentences would.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the tool's behavior well, but for a 7-parameter command with zero schema descriptions it leaves important invocation details unclear. The agent still needs to know which parameters are required for 'complete' versus other statuses, what DiscardComment is for, and how Status values map to integer codes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 0% parameter-description coverage, so the description must compensate. It clarifies Status, EquipmentBookingId, ActualUsageInMinutes, PricePerCountNoOfUnit, and FreeUpSlot indirectly, but DiscardComment and ActualNoOfSlot remain unexplained, and the mapping of logical statuses like 'approve' or 'reject' to integer Status values is absent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Transitions a site equipment booking to a new status', then lists concrete statuses and downstream effects. This clearly identifies the booking as the object and distinguishes it from sibling equipment-status tools like clm_site_equipment_command_update_equipment_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied by the status examples and the booking-specific wording, but the description gives no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives such as clm_site_equipment_command_discard_equipment_booking or the mobile booking update variants, so the agent must infer routing from the name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description explicitly discloses meaningful side effects: updating the related shipment/site-equipment booking, sending a booking-completed email in every supported language, and optionally freeing reserved calendar slots. This gives the agent important behavioral context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one front-loaded sentence that states the action and enumerates side effects compactly. It has no filler, though the long chain of effects makes it slightly dense and run-on.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and annotations, this is a complex destructive command with multiple parameters and zero schema descriptions. The description explains what happens generally but not how to identify the target timeline, which values are expected, or what the completion amount maps to. An agent would struggle to construct correct parameters with confidence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the seven undocumented parameters. It only hints at the completion amount and FreeUpSlot behavior; it does not explain CommandId, TimelineId, ActualNoOfSlot, ActualUsageInMinutes, PricePerCountNoOfUnit, or IsEquipmentCompletedSeparately. Parameter names are somewhat self-explanatory, but not sufficiently defined for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Validates and completes a site-equipment timeline entry.' It then lists concrete side effects (recording completion amount, freeing slots, updating booking, sending notification email), which clearly distinguishes it from sibling timeline list/report tools and other equipment/shipment commands.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly conveys the operation's context: completing a site-equipment timeline entry. However, it does not explicitly state when to prefer this over related commands like updating site-equipment booking status or list/generate timeline tools, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, covering the safety profile. The description adds value by disclosing the bidirectional toggle behavior (add vs. remove driven by a flag) and the 'current user' scoping, which are not present in the annotations. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight sentence with a front-loaded verb and no filler. Every clause carries meaning: action, resource, ownership (current user), and scope (site).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple toggle tool with an output schema and safety annotations present, the description adequately covers purpose and scope. The only meaningful gap is the explicit IsFavourite true/false mapping, which is absent from both the schema and the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so SiteId, MaterialId, and IsFavourite are undocumented in the schema itself. The description partially compensates by mapping 'site' to SiteId, 'material' to MaterialId, and implying the toggle role of IsFavourite, but it never explicitly states that IsFavourite=true adds and IsFavourite=false removes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action pair ('adds or removes') applied to a clear resource ('material from the current user's favorite materials list') with explicit scoping ('for a given site'). It clearly distinguishes this tool from the other user_setting sibling commands, which concern cockpit equipment filters and weekly filters rather than favorites.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided, and no alternative tool is named. Usage is reasonably implied by the resource naming and the user_setting_* command family, but the description would earn a higher score if it stated when this tool should be selected over the filter-related user setting commands.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the `destructiveHint` annotation, the description discloses that this is a logical, non-physical deletion and that it has a side effect: recalculating the owning shipment's incident counts. This gives the agent important behavioral context that annotations alone do not provide, with 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core action, then provides the mechanism and side effect. Every phrase adds meaningful information, and there is no wasted or redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter delete command with an output schema and a `destructiveHint` annotation, the description is largely complete: it explains what is deleted, how, and what downstream effect occurs. The main gap is the lack of explicit parameter guidance, but the nested schema and the tool name make `ItemId` reasonably inferable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden of explaining parameters, but it never mentions `ItemId` or how to specify which incident to delete. The parameter name is somewhat self-explanatory and there is only one parameter, but the description adds no direct meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Soft-deletes an incident'. It goes beyond a generic delete by explaining the exact mechanism (marking as `IsMarkedToDelete`) and distinguishing this from physical removal, which makes the tool's purpose unmistakable even among many delete-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool—when an incident should be deleted—but it does not explicitly name alternatives or state when not to use it. There is no exclusion or comparison to `update_incident` or other incident commands, so usage guidance is only implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation is enriched with precise behavioral detail: in-progress wizard drafts are fully deleted, while submitted shipments only have their pending edit draft and smart-wizard draft cleared. This clearly discloses what gets destroyed and what remains intact, going beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler. It front-loads the core action and uses a conditional structure to compactly convey the two distinct outcomes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is largely complete for a destructive command: it explains the two relevant shipment states, what is deleted, and what is preserved. Minor gaps remain, such as how to handle a null ShipmentId or what error behavior occurs when the shipment does not exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explicitly reference the ShipmentId parameter or explain its semantics. A single parameter is easy to infer, but the description fails to address the nullable default or confirm that a valid ShipmentId must be provided for the discard to take effect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Discards a shipment.' It also distinguishes behavior by shipment state, which differentiates it from siblings like delete_draft_shipment by clarifying when full deletion happens versus clearing only a pending edit draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended context is implied through the state-dependent behavior: use when you want to discard a shipment or its pending edits. However, the description never explicitly guides the agent on when to prefer this over alternatives such as delete_draft_shipment, nor does it mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, and the description adds genuinely valuable behavioral context consistent with those hints: for an already-submitted shipment, the change is 'stored as a pending draft' rather than applied immediately. This prevents an agent from assuming the edit takes immediate effect. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence with a front-loaded verb+resource followed by a colon-separated two-case behavior split. No filler or redundant wording; the semicolon structure makes the direct-apply vs. pending-draft distinction easy to parse, and every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose and the critical draft-vs-direct behavior, and the output schema plus annotations handle return values and safety. However, with ten parameters and zero schema-level documentation, the unexplained weather and schedule-temperature parameters are a real gap, and the near-identical smart-shipment sibling is not addressed. For a tool of this complexity, the description is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the parameter-semantics burden. It maps three of ten parameters to roles (BookingDate, IsExpressShipment, LeanCard). ShipmentId, TimeZone, and TimeZoneOffset are reasonably self-naming, but WeatherSymbolValue, WeatherSymbolTextDe, WeatherSymbolTextEn, and ScheduleTimeTemperature receive no explanation whatsoever, leaving their purpose in the booking-date step unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource ('Saves the booking date step of the shipment wizard'), which clearly differentiates it from sibling wizard-step tools (material, timeslots, unloadings, other_info). It further sharpens the scope by naming the exact fields involved (booking date, express-shipment flag, lean card) and the two shipment states it handles, so an agent knows precisely which step and which context this tool covers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear contextual guidance by spelling out the two shipment states — 'still being created' vs. 'already-submitted shipment being edited' — and what happens in each, so the agent knows the tool applies to both paths. However, it does not explicitly name alternatives or exclusions; notably it never disambiguates from the near-identically named sibling clm_smart_shipment_command_save_shipment_wizard_booking_dates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false. The description adds valuable behavior beyond that: it discloses that zone selection triggers resolution of a waiting area, and — most importantly — that edits to submitted shipments are not applied directly but queued as a pending draft. This state-dependent side-effect disclosure is exactly the kind of context annotations do not carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence that front-loads the core purpose ('Saves the timeslot step') before elaborating the two behavioral branches. Every clause adds information and there is no filler, though the sentence is somewhat long and run-on with nested clauses.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (9 parameters, 0% schema coverage, branching behavior), the description covers the essential flow and the critical state-dependent draft behavior, while an output schema exists to offload return-value documentation. Remaining gaps are the exact roles of Slots and BookingDate, which are partially inferable from context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does map several parameters to concepts: Zone and WaitingArea are linked, the schedule window maps to ScheduleStart/EndDateTime, and equipment reservations map to Bookable/NonBookableEquipments. However, Slots and BookingDate semantics remain unexplained, and the distinction between bookable and non-bookable equipment is not clarified, so compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource ('Saves the timeslot step of the shipment wizard') and explains what that step actually involves: zone resolution, schedule window, equipment reservations, and the draft path. This clearly distinguishes it from sibling wizard-save tools (booking_dates, material, other_info, unloadings) and the smart_shipment variant without needing to open the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when each behavior applies: a shipment still being created applies changes directly, while an already-submitted shipment being edited stores a pending draft. It does not explicitly name alternatives or exclusions, but the 'timeslot step' scoping makes the selection context apparent among the wizard-save siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the destructiveHint annotation by clarifying that the deletion is a soft-delete, that the record is marked as deleted, that the timeline entry is removed, and that an event is logged. These side effects are valuable behavioral disclosures not present in 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence that front-loads the core action and then lists relevant side effects. Every clause earns its place, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with one parameter, an output schema, and a destructive annotation, the description is mostly complete. The main gap is that parameter semantics are not described, and the schema itself provides no description coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain that UnplannedEquipmentId identifies the usage record to delete. The parameter name is self-explanatory to some degree, but the description adds no parameter-level meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('soft-deletes') and a precise resource ('unplanned equipment usage record'), and clearly distinguishes this from related tools like delete_equipment or discard_equipment_booking. It states exactly what the tool does and what effects it has.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear that the tool targets unplanned equipment usage records, but it does not explicitly say when to prefer this over alternatives, nor does it mention any exclusions. Usage context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the important upsert behavior and the condition that controls it, which is meaningful context beyond the idempotentHint and destructiveHint annotations. It stops short of describing edge cases around null values or retries, but the annotations already cover the general safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that front-loads the action and the update condition. The fully qualified 'Commands.EquipmentBookingCommentSaveCommand.ItemId' is slightly redundant, but it does not harm clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations, output schema, and the compact description, an agent can generally determine how to invoke the tool. The main missing piece is explicit guidance on which fields to provide for a new comment versus an edit, especially because all inner parameters are nullable and optional by schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description helps by linking ItemId to existing-comment matching, Comment to the text being edited, and EquipmentBookingId to the target booking. However, it does not explicitly state which parameters are required for create vs edit, nor does it clarify null/default behavior for the three nullable fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific operation: adding a new comment to a site equipment booking or editing an existing comment's text when ItemId matches. This clearly distinguishes the tool from shipment comment tools and from the delete equipment booking comment sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear behavioral condition: use it to add when no matching ItemId exists, and to edit when ItemId matches an existing comment. It does not explicitly name alternatives like delete_equipment_booking_comment or the shipment comment commands, but the scope is clear enough for an agent to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the idempotentHint/destructiveHint annotations by disclosing consequential side effects: assigning a booking number, queuing create-background versus update-background commands (implying async execution), and re-validating the calendar slot reservation. This is exactly the kind of non-obvious behavior an agent needs to know before invoking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single well-structured sentence that front-loads the core purpose before explaining the branching behavior. The drafting-vs-existing conditional and the slot re-validation clause are dense but each earns its place; no filler or repeated schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (so return values need no explanation) and annotations covering safety, the description covers the essential state-dependent behavior, side effects, and domain scope well. The only notable gap is the meaning of ItemId and what happens if calendar slot re-validation fails, but overall an agent has enough to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries the burden of explaining parameters. It semantically maps the parenthetical contents to five of the six params (Photos, Documents, OtherInfoComment, OnSiteResponsiblePerson, CreatorResponsiblePerson), which helps because the schema titles are de-normalized ('Onsiteresponsibleperson'). However, ItemId is never mentioned, and the structure of the Photos/Documents object arrays is left unexplained, so compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: 'Saves the other info step of a site equipment booking,' followed by a parenthetical enumerating the exact contents (creator/on-site responsible persons, photos, documents, comment). This clearly differentiates it from siblings like save_site_equipment_booking_info and save_site_equipment_transport_info, which cover different wizard steps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear contextual guidance about the state-dependent behavior (draft vs. already existing booking), which helps an agent understand when the tool finalizes creation versus updates a draft. However, it never explicitly names alternatives or states when NOT to use this tool versus related siblings (e.g., update_equipment_booking_from_mobile or the other wizard save steps), leaving tool-selection exclusions to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say destructiveHint=false, so the description carries the burden of side-effect disclosure. It explicitly discloses that the incident is linked, shipment counts are recalculated, a background command queues thumbnail generation, and PDF regeneration may be triggered for completed shipments—valuable behavioral detail beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler: the primary action is front-loaded, followed by the side effects and conditional background behavior. Every clause adds information needed for safe invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is strong on behavioral context and return values are covered by the output schema, but the tool has six nested fields with zero schema descriptions and incomplete parameter guidance. It is not complete enough for an agent to reliably fill all parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only loosely maps to Files and ShipmentId. Type, ItemId, Remark, and IncidentType are never defined, leaving an agent unable to construct the params object correctly with confidence.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action and resource: 'Creates a new incident/finding against a CLM, KonsHub, or equipment-booking shipment.' It also states the linking and count-recalculation behavior, and the verb 'creates' clearly separates it from sibling update/delete/get incident tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context—an agent should use this when an incident/finding needs to be created and attached to a shipment. It does not mention explicit when-not-to-use cases or named alternatives, but the creation semantics make the intended use unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation as idempotent and non-destructive. The description adds valuable side-effect context by disclosing that shipment incident counts are recalculated and thumbnail generation is re-queued for updated files, which goes beyond the structured annotation signals.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence that states the fields being updated before the side effects. Every phrase adds useful information, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 details are not required. The description covers the main fields and important side effects, but it does not clarify whether omitted optional fields are left unchanged or cleared, which is a meaningful gap for an update command.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It maps Remark, Files, and IncidentType to 'remark, attached files, and finding type', but it does not explicitly identify ItemId as the incident identifier or explain file object shape and IncidentType integer values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action, 'Updates', a resource, 'an existing incident', and the exact fields involved: remark, attached files, and finding type. This clearly distinguishes it from incident creation and deletion siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'existing incident' gives clear context that this tool is for modifying an already-created incident rather than creating or deleting one. It does not explicitly reference alternatives like create_incident or delete_incident, so it stops 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish readOnlyHint and idempotentHint, and the description adds important behavioral scope: results are limited to the site and the caller's team visibility. It also signals listing behavior beyond the bare 'List shipments'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence communicates the operation, use case, capabilities, and scope with no filler. Every clause adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only paginated list with an output schema and rich parameter descriptions, the description covers the key context: cockpit list usage, site/team scoping, and listing capabilities. It does not explicitly route to related list/search siblings, which is a minor contextual gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all nine parameters, including defaults, bounds, and format. The description restates the general filtering, sorting, and paging concepts but does not add parameter-level detail beyond the schema, matching the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete verb and resource ('List shipments') and adds the cockpit list view context plus the key capabilities: filtered, searched, ordered, and paged, scoped to site and team visibility. This is specific enough for an agent to understand what the tool does and to distinguish it from single-shipment detail tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly ties the tool to the cockpit list view, giving a clear when-to-use context. It stops short of naming alternatives such as clm_search_shipments or clm_count_shipments, so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses multiple side effects beyond the destructiveHint annotation: appends a new handover event with note and photos, updates the parent shipment's aggregated handover status, and queues a background thumbnail-generation job on pause. This gives an agent a clear model of what invoking the tool will change.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary state transition, then side effects in logical order. Every sentence 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the core action, side effects, and key parameters, and an output schema exists so return-value details are not needed. The only notable gap is the undocumented ItemId and somewhat implicit Status semantics, but an agent still has enough context to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no per-property descriptions (0% coverage), and the description only partially compensates. It explains Note, MaterialPhotos, and ResponsiblePersonPhotos via 'note and photos' and the thumbnail job, and clarifies InProgress/Paused as Status values. However, ItemId is never explicitly explained, and there is no guidance on required vs optional fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'Toggles a handover's status between InProgress and Paused,' naming the exact verb, resource, and allowed transitions. This clearly differentiates it from sibling tools like complete_material_handover and create_material_handover.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The toggling language implies use for pausing or resuming a handover, but there is no explicit when-to-use/when-not-to-use guidance and no reference to alternative sibling tools. The existence of complete_material_handover makes this guidance more valuable, but it is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations by specifying that the search covers native CLM and KonsHub-linked shipments and is scoped to a site.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with no filler. The core action is front-loaded, and the scoping/inclusion details are efficiently appended.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with three well-documented parameters and an output schema, the description covers the essential behavioral context. It could optionally differentiate more explicitly from list_shipments, but nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all parameters. The description adds minor semantic context for site scoping, but it does not substantially extend the schema's parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Search'), a clear resource ('shipments'), and the distinguishing mechanism ('by free text, scoped to a site'). It also clarifies that both native CLM and KonsHub-linked shipments are included, making the tool's purpose distinct from list_shipments and get_shipment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this is the tool for free-text shipment search scoped to a site. It does not explicitly name alternatives or exclusions, but the stated use case is sufficiently clear to guide an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the annotations: the command is queued on a message queue, the endpoint returns immediately without waiting, and the email is sent in every supported language. The destructiveHint=true annotation is not directly contradicted; sending an email is an irreversible side-effecting operation, though the description does not spell out whether any data is modified or destroyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with no wasted words. It front-loads the core action (queues a background command), then provides the target condition, email type, language scope, and return behavior. Every phrase contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with an output schema, the description covers the essential context: what action is performed, for which bookings, and the async behavior. It could be more complete by explicitly warning against use for approved bookings or referencing a sibling email tool, but this is a minor gap given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden. It adds meaningful semantic context by indicating the target is a still-open/unapproved site equipment booking, which lets an agent infer that EquipmentBookingId identifies such a booking. However, it does not explicitly explain that EquipmentBookingId must be supplied, what format it should take, or that null is likely invalid for the intended operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 queues a background command that sends a 'booking requested' reminder email for open/unapproved site equipment bookings. It also clearly differentiates this from sibling email tools by naming the resource type and the exact condition (still-open, unapproved). The async queue behavior is explicitly stated, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: use it for still-open, unapproved site equipment bookings, and it explains the async nature and immediate return. It does not explicitly name alternative tools or state when not to use it beyond the 'unapproved' condition, so it falls short of full alternative/exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly discloses important side effects beyond the annotations: on create and update it rebuilds the equipment timeline entry, assigns a booking number, and logs an event. This is meaningful behavioral context that an agent cannot infer from idempotentHint or destructiveHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The primary behavior is front-loaded, and the side effects are listed compactly in the second sentence. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose and side effects well, and the output schema supplies return-value information. However, the seven-field input schema is largely undocumented, and the create-vs-update discriminator is not explained, leaving a meaningful gap for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The phrase 'usage/price/slot data' loosely maps to TotalUsagesInMinute, ActualPricePerNoOfUnit, and ActualNumberOfSlot, but ItemId, EquipmentId, MaterialHandoverId, and Note are not explained. The agent also cannot tell which field identifies the existing record for an update.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the specific resource ('unplanned equipment usage record attached to a material handover') and states the exact action (create or update). It clearly distinguishes this tool from planned-equipment and other equipment-usage siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context: use this when creating or updating unplanned equipment usage data such as usage, price, or slot information for a material handover. It does not explicitly name alternative tools or exclusion conditions, but the intended use case is evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only state idempotent and non-destructive, leaving the description to explain what happens during the save. It does that well: for new shipments it persists material lines and saves each ShipmentMaterial individually, while for existing shipments it stores on the smart-draft instead. This discloses meaningful behavioral nuance beyond 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences with no filler. It front-loads the core purpose, then adds the condition-dependent behavior in the second sentence. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists and annotations cover safety/idempotency, the description covers the essential behavioral split between new and existing shipments. It could be slightly more complete by explicitly routing to sibling wizard-step tools or explaining what a 'smart-draft' is, but nothing critical is missing for invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must carry the parameter-semantics burden. It maps several key concepts to parameters: 'building, floor, laydown area, recipient team' and 'delivery materials'. However, it does not clarify ShipmentId, BookingDate, CommissionedId, MaterialComment, or the distinction/relationship between RecipientTeamId and RecipientTeamName, and the Materials array item shape is left vague.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Saves'), a specific resource ('step 4 of the Smart Shipment wizard'), and the exact content ('delivery materials and drop-off details'). It clearly distinguishes this tool from sibling wizard-step savers by identifying the step and the data involved.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: it is for the Smart Shipment wizard, step 4, and differentiates behavior between new drafts and existing shipments. It does not explicitly name alternative tools or state when not to use it, but the sibling list makes the intended placement fairly inferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the idempotentHint and destructiveHint annotations, the description discloses important behavioral details: it conditionally creates the document only if it does not already exist, and it queues a background command rather than synchronously performing the card operations. This gives the agent a much clearer picture of side effects and async behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the main purpose ('Finalizes the working-package import') before detailing the sequence of actions. Every clause adds meaningful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a one-parameter command with an output schema, idempotentHint=true, and destructiveHint=false, the description covers the essential workflow and async behavior reasonably well. It falls slightly short by not explicitly linking FileId to the uploaded file and by not stating the prerequisite relationship with the upload/mapping sibling tools more directly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 0%, so the description was expected to compensate, but it never mentions FileId or explains how it relates to the operation. The phrase 'uploaded file' weakly hints at the file context, but the actual parameter meaning and its null/default behavior are left undocumented in both schema and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a specific composite action: finalizing the working-package import. It lists two concrete effects — conditional creation of the lean document record and queuing of a background command to create/update lean cards — which distinguishes it from sibling upload/mapping tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this is the final step after an Excel file has been uploaded and mapped, referencing 'previously mapped Excel data' and 'the uploaded file'. It does not explicitly name alternatives or state when not to use it, but the sequential workflow is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as readOnly and idempotent, so no safety disclosure is needed. The description adds behavioral context beyond the schema: the result is organized into bookable and non-bookable groups, and 'all site equipment' indicates full-scope listing. It doesn't cover pagination or ordering, but an output schema exists and the complexity is low.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single compact sentence with no filler, and the grouping behavior is front-loaded immediately after the verb and resource. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple optional-parameter shape, readOnly/idempotent annotations, rich output schema, and a precise one-sentence description, an agent has what it needs to invoke the tool correctly. No critical operational details like required auth or destructive side effects are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter (site_id) is already fully described in the schema, including its default and behavior. The description adds no additional parameter semantics, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List'), names the resource ('site equipment'), and adds a distinguishing detail ('split into bookable and non-bookable groups') plus a UI purpose ('equipment management grid view'). This clearly separates it from siblings like clm_list_equipment_timeline and the many equipment mutation commands.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete context ('equipment management grid view') that tells an agent when this listing tool is appropriate. It does not explicitly name alternatives or exclusion conditions, but the grid-view framing is enough to route selection among the long sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavioral context by stating that deleted incidents are excluded and that the scope is limited to a specific shipment, which is valuable beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that is front-loaded with the action and resource, followed by the scope qualifier. No filler or redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only, idempotent list operation with one required parameter and an output schema present, the description covers everything an agent needs to select and invoke the tool correctly. The non-deleted behavior is explicitly disclosed, and return-value details are covered by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, shipment_id, has a schema description ('The shipment's id.') and the schema coverage is 100%. The tool description does not add extra format or semantic details, but with full schema coverage the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a clear resource ('incidents/findings'), and the scope ('raised against a shipment'). It also adds the 'non-deleted' qualifier, which distinguishes it from a generic incident list and from the singular clm_get_incident sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this tool is used when you need all incidents/findings for a given shipment, and the required shipment_id parameter reinforces that. It does not explicitly name alternatives like clm_get_incident, but the context is clear enough for an agent to route a 'list incidents for shipment' request correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description discloses the critical behavioral nuance: a draft booking is permanently deleted, while an existing valid booking only has its in-progress draft data cleared. This is exactly the kind of side-effect transparency an agent needs before invoking a destructive command.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense sentence with the primary action front-loaded and the conditional behavior clearly separated by a semicolon. Every phrase earns its place, with no filler or repetition of structured metadata.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive one-parameter command, the description covers the target, the action, and the conditional side effects well, and the presence of an output schema reduces the need to explain return values. However, because the description does not explicitly connect the EquipmentBookingId parameter to the booking being discarded, there is slight ambiguity around what value to pass and the null default.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (EquipmentBookingId) with 0% schema description coverage, so the description carries the burden of explaining parameter semantics. The description never mentions EquipmentBookingId, its role, or the fact that it can be null/defaulted, leaving the agent to infer the parameter's meaning from its name alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Discards') and a clear resource ('site equipment booking'), then goes further to explain the two distinct outcomes: permanent deletion for drafts vs. clearing draft data for valid bookings. This precision distinguishes it from sibling tools like delete_equipment_booking_comment and update_site_equipment_booking_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly scopes the tool to 'in-progress' bookings and explains the conditional behavior based on booking state, which tells an agent when this operation applies. It does not explicitly name alternative tools or state when not to use it, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the idempotentHint and destructiveHint annotations, the description discloses the core upsert behavior: it creates a brand-new booking with status UnApproved when none exists for the given id, or updates the existing booking or draft otherwise. It also reveals that drafts are handled by the same call. This is substantive behavioral context the annotations 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences with the primary action front-loaded in the first sentence and the behavioral nuance in the second. No filler, no repetition of the schema, and every clause contributes information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core behavior and step semantics well, and the presence of an output schema obviates return-value documentation. However, the phrase 'for the given id' is ambiguous since the schema exposes both ItemId and EquipmentId, and the many undocumented parameters are not fully compensated for.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage across the 13 parameters, the description carries a high burden and partially compensates by grouping fields into 'booking date, weather info, time slots', which maps onto BookingDate, WeatherSymbol*, ScheduleTimeTemperature, and Slots/BookingFromTime/BookingToTime. However, several parameters (ItemId, EquipmentId, TimeZone, TimeZoneOffset, IsExpressEquipment) receive no semantic clarification, so the compensation is incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('saves') with a precise resource ('the booking-date step of a site equipment booking') and enumerates the step's contents in parentheses (booking date, weather info, time slots). This step-level specificity distinguishes it from sibling step-savers like save_site_equipment_other_info and save_site_equipment_transport_info even without naming them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the tool's context clear: it handles the booking-date portion of a site equipment booking, which conveys a distinct purpose from the other save_site_equipment_* step tools and the shipment wizard tools. It does not, however, explicitly state when not to use it or point to an alternative, so the differentiation is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include idempotentHint=true and destructiveHint=false, and the description adds meaningful behavioral detail: zone resolution including waiting area, and applying the schedule either to the shipment or to its smart-draft depending on shipment validity. This goes beyond the structured annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: two sentences that front-load the core purpose and then add important conditional behavior. It is slightly dense with domain jargon, but every sentence adds value and there is no padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the wizard-step context, the annotation safety profile, and the presence of an output schema, the description is sufficiently complete for an agent to select and call this tool correctly. The only minor gap is less explicit documentation of the exact time-slot-related parameters, but this is partially covered by the schema itself.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden of explaining parameters. It maps well to most parameters: 'unloading zone' to Zone, 'delivery time slots' to Slots, 'bookable/non-bookable equipment' to the two equipment arrays, and 'schedule' to the schedule start/end fields. It does not explicitly describe BookingDate or NumberOfSlot, but the overall semantics are substantially clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Saves'), a precise resource ('step 2 of the Smart Shipment wizard'), and the exact data involved: unloading zone, delivery time slots, and bookable/non-bookable equipment. This differentiates it from sibling wizard-step tools such as booking_dates, materials, and other_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context about when this is used ('step 2 of the Smart Shipment wizard') and explains the conditional behavior for direct shipments vs smart-drafts. It does not explicitly name alternatives or exclusions, but the step and domain context make the intended usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the idempotent and non-destructive annotations, the description discloses significant behavior: calendar reservation with rollback on failure, draft-to-real-shipment promotion, conditional status change via HasAction, grouping count updates, and asynchronous ClmCommand queueing. This adds substantial operational context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence carries useful information: purpose first, then validation behavior, then update/new success paths, then async queueing. The structure is logical and front-loaded with the tool's primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description thoroughly covers side effects and downstream processing, but omits important operational details: what SaveAsDraft=true changes, how to indicate an update versus a new shipment, and what identifiers such as ShipmentId/GroupingId are for. These matter especially because all inner parameters are optional and the schema provides no descriptions. Output schema exists, so return values are adequately covered elsewhere.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It maps several parameter groups (comment, photos/documents, responsible persons, sustainability) and explicitly explains HasAction's role. However, it leaves ActionCode, ActionType, GroupingId, GroupingType, ShipmentId, BookingDate, and SaveAsDraft semantics largely to inference, and does not clarify how the agent signals an update versus a new shipment.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Saves the final step of the Smart Shipment wizard') and enumerates the exact content areas: responsible persons, photos/documents, comment, and sustainability info. It clearly distinguishes this from the sibling wizard-step tools by positioning it as the final step and explaining finalization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'final step of the Smart Shipment wizard' gives clear context for when the tool should be called, especially alongside sibling tools for materials, timeslots, and unloadings. It does not explicitly say 'do not use for other wizard steps' or name alternatives, but the intended usage is apparent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important non-obvious behavior: if no shipment exists for the ShipmentId, it creates a new UnApproved draft linked to the lean card's site; otherwise it updates the existing shipment or its smart-draft. This goes well beyond the idempotentHint and destructiveHint annotations and clarifies the tool's conditional side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The first sentence front-loads the primary purpose and scope, and the second provides essential conditional behavior. Every sentence contributes operational information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately covers the tool's central complexity: conditional creation vs update, draft status, site linkage, and smart-draft behavior. The output schema can cover return values. It falls slightly short of full completeness because some parameters are not explicitly explained and null ShipmentId behavior is not addressed, but an agent can still invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains ShipmentId's conditional create-vs-update semantics and groups BookingDate, LeanCard, TimeZone, TimeZoneOffset, and WeatherSymbol fields into meaningful categories. However, IsExpressShipment and ScheduleTimeTemperature are not mentioned, and LeanCard's internal structure is left unspecified, so compensation is only partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: it saves step 1 of the Smart Shipment wizard, covering booking date, lean card, and weather/timezone context. This is specific enough to distinguish it from sibling wizard-step tools such as save_shipment_wizard_material or save_shipment_wizard_timeslots.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly identifies the use case as the first step of the Smart Shipment wizard and explicitly lists the fields involved. It does not explicitly name alternatives or say 'use this instead of X', but the step-1 and booking-date framing gives strong contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavior beyond the annotations: it explains that the vehicle information is applied either directly to the shipment or to its smart-draft if the shipment already exists as a valid non-draft shipment. This conditional behavior is useful and not expressed by the idempotentHint or destructiveHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The core purpose is stated first, and the important conditional smart-draft behavior is added in the second sentence. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The definition is complete for a wizard-step save command: it identifies the step, the key data, and the draft-vs-valid-shipment behavior. An output schema exists so return values don't need to be described. A small gap is not explaining prerequisites or how the wizard step relates to the other wizard steps, but this is not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: 'unloading vehicle details' maps to Vehicle, 'shipment' maps to ShipmentId, and 'booking date' maps to BookingDate. It doesn't explain the inner shape of the Vehicle object, but the schema itself treats it as a generic object, so this is acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('saves step 3 of the Smart Shipment wizard'), the resource ('unloading vehicle details'), and the scope ('for the shipment's booking date'). This is a specific verb+resource combination that distinguishes it from the other wizard-step save tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when to use the tool: when saving step 3 of the Smart Shipment wizard, specifically unloading vehicle details. It does not explicitly name alternatives or exclusions, such as the regular (non-smart) shipment unloadings sibling, so it stops 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context by revealing that the record may have up to 142 fields, most of which are typically absent, preparing the agent for sparse or large responses.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, with the core action and scope front-loaded. The sibling alternative is included in a compact second sentence, making the description both efficient and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read operation with full schema coverage, read-only annotations, an output schema, and an explicit alternative, the description covers everything an agent needs to invoke and interpret the tool correctly. No critical context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single required parameter is already documented as 'The shipment's id.' The description reinforces lookup 'by id' but does not add extra format, source, or domain nuance beyond what the schema provides, which is acceptable given full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('Retrieve') and resource ('full internal shipment record by id'), and clearly distinguishes itself from the sibling clm_get_shipment_summary by calling itself 'full internal' versus 'smaller, external-facing'. An agent can immediately tell what this tool returns and how it differs from the nearest alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs the agent to prefer clm_get_shipment_summary for a smaller, external-facing view, which provides a clear selection rule between siblings. This is direct when-to-use guidance rather than leaving the choice implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the idempotent and non-destructive annotations, the description discloses meaningful side effects: it queues background building of a preview, matches rows against existing teams and lean cards, and notifies the uploading user of the outcome. This async behavior is not inferable from the 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence, but it front-loads the primary action and then lists the consequential side effects without redundancy. Splitting it into two sentences would improve readability, but every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the prerequisite (previously uploaded file), the action (saving the mapping), and the postconditions (background preview build and user notification). Given the output schema exists, not detailing return values is acceptable; the main remaining gap is the precise shape of MappedHeaders and what values DateFormat accepts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description gives semantic anchors for the key parameters: FileId via 'previously uploaded working-package file', DateFormat via 'date format', SenderTeamId/RecipientTeamId via 'sender/recipient team', and MappedHeaders via 'mapping between Excel columns and lean card fields'. It stops short of specifying the exact structure of MappedHeaders or accepted date formats, but it compensates well for the schema's silence.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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: saving the mapping between Excel columns and lean card fields for a previously uploaded working-package file. It also names the concrete fields involved (activity id, date format, sender/recipient team), which clearly distinguishes this from sibling upload and file-data tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly situates the tool in a workflow: it operates on 'a previously uploaded working-package file' and subsequently queues preview building. It does not explicitly name alternatives or state when not to use it, but the intended context is strongly implied and easy to follow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds meaningful behavioral context: the enums are undocumented integer values, real member names are unknown, and placeholder names are interchangeable with integer values. This is exactly the kind of non-obvious behavior an agent needs to know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core purpose is stated in the first sentence, and the supporting detail about placeholder names is confined to a short second paragraph. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only listing tool with an output schema, the description is complete. It explains why the enums exist, how they are represented, and how the returned values are used by other tools. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema has 100% coverage of that, so there is nothing for the description to explain about parameters. The description appropriately focuses on the output's meaning instead.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource ('List CLM domain enums and their known integer values'), which immediately identifies the tool's purpose. It is clearly distinguishable from all sibling tools, none of which are enum-listing utilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that enum values are shared across tools and that tools accept either the integer value or the placeholder name interchangeably. This gives practical usage context for when an agent would want this information, though it does not explicitly say 'call this before using tools that accept enum parameters' or mention exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful behavioral context: it returns operation names/summaries rather than schemas, supports exact tag and case-insensitive substring filtering, and routes full schema retrieval to clm_describe_operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler. The purpose is front-loaded, the filters are compactly specified, and the next step is actionable. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple optional-parameter tool with an output schema and annotations covering the safety profile. The description tells the agent what the tool returns, how to filter, and what to do afterward, so it is complete for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description compensates for tag and search with precise semantics: exact tag match and case-insensitive substring on name/summary. Limit is not described, but its name and default value make its purpose reasonably self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'List CLM API operations reachable via clm_invoke.' This clearly distinguishes it from sibling describe/invoke tools and entity-specific listers. The filter details and next-step guidance reinforce its discovery role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly frames the workflow: list operations, then 'Use clm_describe_operation on a result to get its full input schema before calling clm_invoke.' This gives when to use the tool and the recommended follow-up, though it does not spell out when not to use it or name specific alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the destructiveHint annotation by disclosing that deletion is permanent, that background commands are queued, and that behavior is conditional for bookable equipment. This gives the agent a strong understanding of side effects and irreversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. It states the core action first, then adds valuable detail about side effects and conditional behavior. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive command with an output schema, the description is complete: it states the target resource, permanence, queued background actions, and condition for bookable equipment. No critical behavioral information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, but EquipmentId is self-descriptive and the deletion action implies it identifies the target site equipment record. However, the description does not explicitly explain how to use EquipmentId or address the parameter's null default, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Permanently deletes a site equipment record.' It also uniquely describes cascading behavior by queuing background commands to remove zone attachments and booking prerequisites, which distinguishes it from sibling delete/discard tools. This is clear and specific enough for an agent to understand what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: when a site equipment record needs to be permanently deleted along with its associated cleanup. It does not explicitly name alternatives or exclusions, but the resource scope is clear enough that an agent can infer the appropriate usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool read-only and idempotent, and the description adds meaningful extra behavior: it may trigger a token refresh and serves as an authentication check. It also reveals that the returned site_id is the implicit default for sibling tools, which is valuable runtime context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The primary purpose is front-loaded, and the usage guidance is compact but informative. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with annotations covering safety and an output schema present, the description covers purpose, invocation ordering, authentication behavior, and the cross-tool significance of site_id. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is empty and the description does not need to explain parameter meanings. The baseline of 4 applies because there is nothing to document beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb, 'Return', and names the exact resource: the identity, site, and roles of the authenticated CLM user. This clearly differentiates it from the many shipment, incident, and equipment sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to 'Call this first' and explains why: it confirms authentication, may trigger a token refresh, and provides the site_id that other tools rely on. This gives clear when-to-use guidance and practical context for ordering calls.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

clm-mcp MCP server – quality and maintenance score on Glama

Copy to your README.md:

[![clm-mcp MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/sabadia/clm-mcp/badges/card.svg)](https://glama.ai/mcp/servers/sabadia/clm-mcp)

Score Badge

Copy to your README.md:

[![clm-mcp MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/sabadia/clm-mcp/badges/score.svg)](https://glama.ai/mcp/servers/sabadia/clm-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/sabadia/clm-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server