BerthTime

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is fully carried by structured data. The description adds two useful behaviors beyond that: the 'active shipments' scope filter and the soonest-first ordering, but says nothing about pagination or result size behavior despite a limit parameter.

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

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

One short sentence, front-loaded with the resource and the filter, then the ordering. Nothing redundant.

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

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

A simple read-only list tool with annotations covering safety, so a terse description is defensible. However, the undescribed limit cap and the absent mention of what a shipment result contains leave gaps for an agent choosing how wide to query.

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

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

Schema coverage is 67%; days and company are documented in the schema, and the description only echoes the default of 7 for days. The limit parameter is undocumented in both schema and description, so the description does not compensate for that gap.

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

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

States a specific resource and filter: active shipments with an ETA inside a look-ahead window, returned soonest-first. An agent can tell this apart from delayed_shipments by the 'Active' qualifier, though the sibling is never named explicitly.

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

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

The sense of 'upcoming arrivals' is implied by 'ETA falls within the next N days', but there is no explicit when-to-use, when-not-to-use, or pointer to delayed_shipments or list_shipments for other queries.

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

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

Annotations already cover readOnly, idempotent, non-destructive and closed-world, so the safety profile is handled. The description adds genuine domain behavior beyond that: it defines 'delayed' as a slip against the first ETA BerthTime observed (not the scheduled ETA), which materially changes how results should be interpreted, and it discloses the sort order. Pagination/limit behavior is not mentioned.

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

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

A single dense sentence with the core filter front-loaded and no wasted words. It reads as a noun phrase rather than a complete sentence, which is slightly abrupt but does not cost clarity.

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

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

For a three-optional-parameter read tool with no output schema, the description covers the filter and ordering but leaves open what 'Active' means and what a returned shipment record contains, and never says that limit caps the result count. Adequate, but an agent still has gaps to fill.

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

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

Schema coverage is 67%, with company and min_delay_hours already documented in the schema; the description mainly repeats the min_delay_hours default of 24 rather than adding meaning. The limit parameter has no description anywhere and its interaction with the result set is unexplained. This is a baseline-level contribution for a partially covered schema.

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

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

The description states a precise resource and filter: 'Active shipments whose ETA has slipped versus the first ETA BerthTime saw, by at least min_delay_hours'. That is far more specific than a name restatement and pins down the exact delay definition and ordering. It does not explicitly distinguish itself from the close sibling arriving_soon or list_shipments, which keeps it from a 5.

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

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

Usage is only implied through the filter semantics: an agent can infer this is the tool for 'which shipments are running late', but there is no explicit when-to-use or when-to-prefer-over guidance versus arriving_soon, list_shipments, or get_shipment_events. No exclusions or prerequisites are stated.

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

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

The description adds one real behavioral fact beyond the annotations: 'Stores nothing,' which matters for an agent handling untrusted input. The annotations already carry readOnly, idempotent, non-destructive and closed-world hints, but the description does not disclose confidence/uncertainty behavior or that the result is a heuristic guess with partial failure modes.

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

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

A single sentence front-loads the classification purpose and ends with the storage caveat; no filler, no restating the title.

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

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

For a one-parameter, read-only, closed-world classifier with full schema coverage and no output schema, the description is nearly sufficient. The main omission is what the response contains (e.g. type, carrier name, confidence/validity flag), which an agent must know to interpret results since there is no output schema.

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

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

Schema coverage is 100% and the single parameter's description 'Container, bill of lading or booking number' already mirrors the tool description. The description adds no format detail (e.g. whitespace, hyphens, case sensitivity, or the 3-64 length constraint's practical implications), so it stays at the baseline.

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

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

The description uses a specific verb ('Guess whether') plus the exact resource ('a number') and enumerates the three reference kinds it classifies (container with ISO 6346 check digit, bill of lading, booking number), plus carrier identification. No sibling tool does classification, so its role among list_*/get_* siblings is unambiguous.

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

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

It makes the input condition clear ('whether a number is...'), which implies when to call it: when you have an unidentified reference string. However, it names no alternatives and gives no exclusions, e.g. that it is unnecessary for already-known shipment IDs or that get_shipment should follow if a match is found.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile needs no restating. The description adds genuine behavioral context by disclosing the payload shape, and notably flags that position is an estimate and times are actual/estimated rather than guaranteed. It stops short of saying the event list is truncated by the events parameter (default 5, max 50) or that results are scoped by company.

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

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

A single sentence with the resource and identifier forms front-loaded, followed by a tight enumeration of the returned sections. No filler, no restatement of the title, and the parenthetical route detail is information-dense rather than verbose.

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

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

With no output schema, the description carries the return-value burden and does so well by listing summary, route, position, ETA and latest events. The main remaining gap is that it never ties the events parameter to the returned event list or explains company scoping, so an agent cannot predict result size or tenancy behavior from the description alone.

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

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

Schema coverage is 100%, so the schema already documents all three parameters including the accepted identifier forms and the events count semantics. The description's restatement of the identifier types adds little beyond that, and it never mentions the company scoping parameter or the events cap. Baseline 3 is appropriate when the schema carries the parameter documentation.

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

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

Names a specific resource (one shipment) and enumerates exactly what comes back: summary, route with POL/transshipments/POD and actual vs estimated times, position estimate, ETA and latest events. The three accepted identifier forms (BerthTime id, tracked reference, container number) make it clearly distinguishable from get_shipment_events, which appears to return only the events slice.

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

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

Usage is implied by the identifier list, so an agent knows how to call it, but there is no explicit when-to-use guidance: no statement that get_shipment_events should be used when only events are needed, and no mention of detect_reference as the way to resolve an unknown reference string first. No when-not or prerequisite conditions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile needs no restating. The description adds real behavioural context the annotations do not cover: what the returned data actually is (a DCSA event timeline), its ordering (oldest first), and the meaning of the ACT/EST/PLN status codes, which matters because there is no output schema.

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

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

It is two tight sentences with the resource and ordering front-loaded and no filler. The second sentence restates the enum meanings already present in the schema, which is mildly redundant, but it stays brief and readable.

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

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

With no output schema, the description carries the burden of describing what comes back; it does partially (event kinds, chronological order, status code meanings) but omits any indication of per-event fields or whether location/vessel/timestamp data accompanies each event. For a read-only list tool with full schema coverage this is adequate but leaves a gap on return shape.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, including the shipment reference forms and the limit semantics ('most recent N events, returned oldest first'). The description adds nothing beyond that; its ACT/EST/PLN gloss is a near-duplicate of the classifier enum description, so baseline 3 applies.

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

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

The description names a specific resource and shape: the DCSA-style event timeline of a shipment, with example event types (gate in, load, departure, arrival, discharge) and an ordering guarantee (oldest first). It is clearly distinguishable from get_shipment or arriving_soon by implication, though it never explicitly contrasts with those siblings.

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

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

Usage is only implied: an agent wanting a milestone history rather than a current-state snapshot would pick this. There is no explicit when-to-use statement, no mention of get_shipment as the alternative for shipment attributes, and no note on prerequisites such as needing a valid shipment reference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds one genuinely useful rule beyond annotations: a shipment counts once per month only when the carrier returned data for it, which explains the counting semantics. It does not cover auth requirements, permissions across companies, or cost/currency behavior.

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

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

Two sentences, front-loaded with the core purpose and return contents, followed by the one non-obvious counting rule. No filler or redundancy.

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

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

For a 3-parameter read-only tool with full schema coverage and no output schema, the description covers purpose, default scope, and the counting semantics adequately. Minor gaps remain around multi-company permissions and what cost/currency values represent, but nothing prevents correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents month format, company identifier, and include_shipments. The description adds only the default-month behavior (already in the schema) and no further meaning beyond the shipment-counting rule. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

States a specific verb-and-resource: retrieves the company's plan and billable shipment usage for a month, enumerating what is returned (allowance, used, overage, cost, trial end). It is clearly distinct from sibling tools like get_shipment or list_shipments, though it doesn't explicitly name those siblings to route the agent.

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

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

Usage is implied by the description (billing/usage questions for a given month, defaulting to this month) but there is no explicit when-to-use vs when-not-to-use guidance or mention of alternatives such as list_shipments for raw shipment listing. The include_shipments flag hints at the boundary with list_shipments, but only indirectly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed-world scope, so safety is covered. The description adds value by disclosing the shape of the returned records (SCAC, name, per-type support, live status) in the absence of an output schema, and the word 'today' signals the live flag is time-sensitive. It does not mention pagination or ordering, which is a minor gap for a list tool.

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

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

One dense sentence with zero filler, front-loading the resource and then the returned fields. It is a sentence fragment rather than a well-formed statement, but nothing is wasted and the key information comes first.

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

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

For a one-parameter, read-only, non-destructive lookup with no output schema, the description covers purpose and return content adequately, and annotations cover the safety profile. The missing piece is explicit guidance on when an agent should reach for this tool versus its siblings, but for a simple reference tool the definition is largely complete.

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

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

Schema description coverage is 100% and the single parameter live_only is fully documented in the schema itself. The description's 'whether tracking is live today' loosely echoes that filter but adds no syntax, default, or interaction detail beyond what the schema states. Baseline 3 applies when the schema carries the semantics.

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

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

The description names a specific resource (carriers BerthTime knows) and enumerates the data returned per carrier: SCAC, name, supported reference types, and live-tracking status. That is far more precise than a tautology and clearly distinguishes it from shipment-centric siblings like list_shipments or get_shipment. It stops short of an explicit verb ('list'), relying on the title for that framing.

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

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

There is no when-to-use or when-not-to-use guidance and no named alternative. An agent must infer that this is the reference/lookup tool to call before resolving a carrier elsewhere. The phrase 'whether tracking is live today' hints at a filtering use case but never states it as guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description goes beyond that by disclosing the returned content (identity, default company name/@handle/plan, per-company read vs read+write access), which the agent could not infer from the schema or annotations.

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

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

Two sentences, no filler, with the identity/default-company summary front-loaded before the cross-tool hint. The parenthetical enumerations are dense but each item (plan, access level, handle format) carries real information.

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

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

There is no output schema, so the description must convey what comes back, and it does: acting identity, default company details, all accessible companies, and access levels. For a zero-parameter, read-only tool this is nearly sufficient; only the exact response shape and ordering are left unstated.

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

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

With zero input parameters the baseline is 4. The description still adds value by explaining the `company` identifier convention (id, @handle or name) that this tool's output feeds into other company-scoped tools.

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

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

The description specifies the resource precisely: the acting identity (user or API key), its default company, and all companies it can act for. The '(a.k.a. whoami)' alias removes ambiguity about the tool's role, though the phrasing is nominal rather than a verb+resource statement.

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

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

It implicitly establishes this as the discovery/identity tool and adds a useful cross-tool rule: 'Company tools take `company` (id, @handle or name) to pick one.' That links the output to how sibling tools are invoked, but there is no explicit when-not-to-use guidance or named alternative.

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

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

The annotations already establish read-only, idempotent, non-destructive, closed-world behavior, and the description's 'Read only' adds nothing beyond them. It does add useful context about the returned rule types, scopes, and recipient counts, but provides no further operational details such as pagination or empty-result behavior.

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

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

The compact statement front-loads the resource and then efficiently summarizes its types, scopes, and recipient-count output. The final 'Read only' is redundant with the annotations but adds negligible bulk.

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

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

For a simple read-only listing with two optional, fully documented parameters, the description and schema provide enough information to select and invoke the tool correctly. Because there is no output schema, the description's summary of rule types, scopes, and recipient counts is especially useful for setting result expectations.

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

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

Schema description coverage is 100%, and both parameters already explain company selection, the default company, and inclusion of paused rules. The description's generic reference to 'the company's' rules adds no meaningful parameter guidance, making the high-coverage baseline of 3 appropriate.

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

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

The description precisely identifies the resource as a company's email alert rules and usefully enumerates rule types, scopes, and recipient counts. Although phrased as a noun phrase rather than with an explicit list verb, its subject matter clearly distinguishes it from siblings that retrieve shipments, carriers, companies, or tickets.

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

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

It provides clear context for inspecting notification-rule configuration rather than shipment status or events. It does not give explicit when-not guidance or name an alternative tool, so it falls short of a 5.

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

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

Annotations already carry readOnlyHint, idempotentHint and destructiveHint=false, so the 'read-only' repetition earns nothing. What does add value is the disclosure that these records are invisible to the sibling tools and that filter=requests narrows to open tracking requests, which is real behavioral context 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.

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

Two sentences, no filler, with the scope statement front-loaded before the field list and the exclusions. The mid-sentence field enumeration is slightly dense but each element carries information an agent needs since there is no output schema.

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

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

For a five-parameter read tool with no output schema, the description usefully reports the returned fields (owner, carrier, POL/POD, phase, ETA) and the requests filter. Pagination behavior and the company-default semantics are left entirely to the schema, which is an acceptable but not complete handoff.

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

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

Schema coverage is 80%, so the schema already documents q, filter, company and cursor. The description only reinforces the filter=requests case and adds no detail on q, limit, cursor, or the company parameter's @handle/id/name forms; the field list it gives describes return values rather than inputs. Baseline 3 applies.

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

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

States a specific verb and resource ('Shipments other companies... shared with this company') and enumerates the visible fields (owner @handle, carrier, POL/POD, phase, ETA). The closing sentences explicitly mark it off from the company's own shipments and note that the other tools cannot see these records, so an agent can tell it apart from list_shipments without opening either schema.

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

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

Gives clear context for when this tool applies (network-shared shipments) and names the filter=requests mode for open tracking requests. It never names list_shipments as the alternative for own shipments, leaving that routing to inference, but the 'the other tools do not see them' line makes the boundary clear enough.

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

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

The annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real value beyond that by disclosing the default sort (newest first) and the fields returned (carrier, POL/POD, phase, ETA, delay), which matters because there is no output schema. It stays silent on pagination behavior and how the default 'active' scope affects result counts.

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

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

Two sentences with no filler: the first establishes resource, scope, ordering and output fields, and the second compresses all filterable dimensions into one clause. Information is front-loaded and nothing is repeated from the annotations.

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

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

For an 11-parameter, no-required-arg list tool with no output schema, the description covers what the tool returns and how to narrow results, which is the essential gap. The remaining shortfall is pagination guidance (limit/cursor interaction) and the unexplained eta_risk filter, neither of which appears in the description.

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

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

Schema description coverage is 73%, so the schema already documents most parameters including q, status, carrier, eta_after/eta_before and company. The description largely restates those same filter categories rather than adding syntax or semantics, and it omits any mention of limit, cursor, or eta_risk. Baseline 3 is appropriate given the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource ("List the company's tracked shipments") and adds sort order and returned fields, which is far more informative than the title. It does not name or distinguish itself from close siblings such as delayed_shipments or arriving_soon, so an agent must infer the boundary from the filter list.

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

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

Usage is only implied through the enumeration of filters (status, carrier, phase, tag, ETA window, free-text), which hints at when the tool fits. There is no explicit statement of when to prefer this over delayed_shipments or arriving_soon, and no exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds one genuinely useful behavioral fact beyond that: internal staff notes are never returned, which tells the agent the output is a filtered projection. It stops short of describing ordering, pagination, or default result size behavior.

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

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

A single tight sentence with the scope up front and the exclusion clause last; nothing is redundant. It is arguably too terse rather than padded, but every clause earns its place.

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

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

With no output schema, the parenthetical field list usefully compensates by describing the shape of each result, and the exclusion note clarifies the data boundary. For a paginated list tool it still omits ordering, total/cursor behavior, and result-count limits, which an agent needs to call it safely at scale.

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

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

Schema description coverage is only 67%, and the description adds no parameter meaning at all — it never mentions filtering, the 'active = open + pending' default, or the company resolution. The undocumented 'limit' parameter and the effect of combining status with company are left entirely to the schema, which does not cover them.

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

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

The description names the resource and its scope ('The company's support requests to the BerthTime team') and enumerates the visible fields (number BT-1234, subject, status, last activity), so an agent can tell it is not list_shipments or list_carriers. However, it is a noun phrase with no verb, so 'list' is only inferred from the tool name rather than stated, and no sibling is named for contrast.

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

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

There is no guidance on when to choose this tool over the other list_* siblings, no mention of how the limit/status/company parameters should be used to narrow results, and no prerequisites. The only scope remark is that internal notes are excluded, which is a data-visibility fact rather than usage advice.

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