Trackberry

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds a genuinely useful edge case not in annotations or schema: `fields` is empty when nothing could be extracted. It does not discuss error behavior or extraction latency.

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

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

Front-loads the core purpose, then layers document-type examples, the return-shape keys, and the empty-fields caveat. Every sentence earns its place; no filler.

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

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

There is no output schema, so the description carries the return-value burden and does so by naming `type`, `schema`, and `fields` and noting when `fields` is empty. For a single-param read tool this is 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 coverage is 100% and there is a single parameter, so the baseline is 3. The description goes beyond by cross-referencing the source of the id (list_documents), which orients the agent on how to obtain a valid value.

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 (retrieve structured fields extracted from one document) and concretely enumerates what those fields are per document type (parties/ports/vessel for a B/L, amounts/terms for an invoice). This distinguishes it from siblings like get_document_file (raw file) and list_documents (ids only).

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 concrete example queries ('what is the invoice total on doc_45', 'who is the consignee on the B/L') and tells the agent where to source ids (list_documents). It lacks an explicit when-not/alternative statement (e.g. vs get_document_file), but the routing context is clear.

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

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

Annotations already declare it read-only, idempotent, and non-destructive, but the description adds substantial operational context beyond them: which formats are readable, size ceilings (5 MB PDF / 3.75 MB images / 200 KB text), and that spreadsheets cannot be read here. This is exactly the value-add the annotation baseline asks for.

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

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

Front-loaded with what the tool returns, then routing guidance, prerequisite, and limits. Five sentences all carry distinct load; none is filler.

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

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

With no output schema, the description compensates by describing the return shape per format, and it covers the routing, prerequisite, and size/format constraints an agent needs to call this correctly. Nothing material is missing.

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

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

Only one parameter and schema coverage is 100%, so the schema fully documents document_id including its list_documents origin. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific resource (the original file of one document) and concretely describes what comes back per format (PDF as file, image as image, text/CSV as text). It is clearly distinguishable from get_document_data, which is named as the structured-data alternative.

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

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

Explicit when-to-use (when get_document_data lacks the answer, to verify a value, or when the user asks to see the document), explicit when-not/prefer alternative (prefer get_document_data first because it is smaller and structured), and a hard prerequisite (only `downloadable` true documents have a file).

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, so the safety profile is covered. The description adds genuinely non-structured behavioral context: which ETA field to quote, that public_tracking_url is null when public pages are off / shipment archived / not yet live, and that URLs must never be invented.

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

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

Front-loads the payload summary, then routes to alternatives, then handles the two URL fields. Dense and purposeful, though the URL/ETA caveats make it longer than strictly minimal; every sentence still does work.

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?

No output schema exists, so the description carries the return-value burden — and it does so by listing the returned categories plus the ETA-field and nullability semantics. An agent can call this and interpret the response without further documentation.

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?

Only one parameter, fully documented in the schema (100% coverage, including the shp_123 format and its source search_shipments). The description adds no further parameter-level detail, so the baseline 3 for schema-carried params 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?

Opens with a specific verb and resource ('Everything about one shipment') and then enumerates the exact payload surface (status, route, ETA, carrier, parties, cargo, containers, labels, check counts, notes, free_time). It is immediately distinguishable from siblings like get_tracking_timeline and list_documents.

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

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

Gives explicit trigger phrases ('when does it arrive', 'how many free days are left') and names alternatives with their selecting conditions: get_tracking_timeline for current position/route, list_documents for paperwork. Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's real contribution is behavioral: the truncation rule (only the most recent `event_limit` events, 40 by default, `events_total` gives the full count) and the eta_revisions shape (previous/new date plus slip in seconds). It omits anything about auth, quotas, or ordering caveats, but for a read tool the truncation semantics are the key disclosure and they are present.

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

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

Front-loaded with the core capability, then usage triggers, then return detail, then the routing exclusion. Dense and largely waste-free, though the quoted example-utterances list is longer than strictly necessary.

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

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

With no output schema, the description carries the burden of describing returns and does so: route legs, ordered events with place/time/coordinates, eta_revisions with previous/new dates and slip seconds, plus the map rendering for MCP Apps clients. Nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond the schema by explaining what `event_limit` actually does (windows the most recent events) and pairing it with the `events_total` counter that reports the unfiltered count. That is meaningful semantics an agent could not derive from the schema alone.

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

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

Opens with a specific verb+resource scope ('The journey of one shipment') and enumerates the payload components (route legs, events, eta revisions). It also explicitly names the sibling it is not — search_shipments' `latest_event` — so an agent can distinguish it 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?

Provides concrete triggering phrasings ('what happened to shipment shp_123', 'has the ETA moved') plus an explicit when-not: for a list of shipments, use search_shipments' `latest_event` rather than calling this per shipment. Both the use case and the anti-pattern 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?

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the description does not need to restate safety. It adds genuinely useful context beyond that: the return shape (two lists, newest first, capped at limit) and the shipment_url linking obligation, which prevents fabricated URLs.

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?

Well front-loaded: what the tool surfaces, then when to use it, then the return shape, then the URL guidance. The prose is dense but each sentence carries information; only the shipment_url sentence is arguably output-formatting that could be trimmed.

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 explaining returns and does so adequately (two lists, newest first, limit-bounded, shipment_url per entry). It omits anything about empty results or error conditions, which is a minor gap for a read-only listing tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds one meaningful nuance, clarifying that limit caps each list rather than the combined result, and that shipment_id narrows to a single shipment, but it provides no format or edge-case detail beyond that.

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 frame ("open monitoring alerts... and shipment checks that failed or raised a warning") and enumerates concrete alert categories, so an agent knows exactly which data it returns and can distinguish it from siblings like get_shipment or list_free_time_at_risk.

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

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

It gives explicit triggering intents ("anything wrong with my shipments", and "is shipment shp_123 healthy" with shipment_id), which maps cleanly to whether to pass the optional parameter. It stops short of naming alternative tools or exclusions, which is the only gap.

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, closed-world and non-destructive, so the safety profile is settled. The description adds value beyond that by describing the shape of each returned entry and warning not to fabricate shipment_url values, but it says nothing about pagination or result-size limits.

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

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

Front-loaded with purpose and contents, then usage examples, then sibling routing. Every sentence earns its place except the trailing shipment_url caveat, which is useful but slightly tangential to the tool's core job.

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 correctly carries the burden of describing return entries (id, type, file name, processing status) and how to use shipment_url. An agent has everything needed to call and interpret this tool.

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 is fully documented in the schema with the same 'shp_123' example the description uses, so the description adds no meaning beyond it. Baseline 3 applies when 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+resource (list a shipment's documents) and enumerates the concrete contents (bill of lading, invoice, packing list, id, type, file name, status). It clearly differentiates itself from get_document_data and get_document_file, which are named directly.

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

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

Gives explicit when-to-use examples ('which documents does shipment shp_123 have', 'is the certificate of origin missing') and routes the agent to the correct alternatives with conditions: get_document_data for content, get_document_file when `downloadable` is true.

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 the safe read-only/idempotent profile, and the description adds real behavioral context beyond them: the 45-day discharge window, urgency ordering, the demurrage/detention clock semantics with days-left and active clock, the meaning of terms_unknown, and the instruction to use the provided shipment_url rather than fabricate one.

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

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

Front-loads the resource and urgency ordering, then packs output semantics and the URL-safety rule into tight sentences. With no output schema, none of the return-value detail is redundant, and nothing is padding.

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 parameterless list tool with no output schema needs the description to carry the return-shape burden, and it does: clock fields, terms_unknown, and the shipment_url linking rule are all present. An agent can call and render this correctly from the text 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?

Zero parameters, so per the baseline this is a 4. 'Takes no arguments' simply confirms what the empty schema already shows, adding no new parameter meaning.

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 scope: ocean shipments whose demurrage/detention free time is running out or already over, sorted most urgent first. This is unambiguous and clearly separable from generic siblings like search_shipments or list_alerts.

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 two concrete trigger questions ('what will cost us demurrage this week', 'which containers should we pick up first') plus a hard scope constraint (discharged in the last 45 days only). It stops short of naming an explicit alternative or when-not condition, but the intended use is obvious.

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

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

With annotations declaring readOnlyHint=true, idempotentHint=true, destructiveHint=false and closed-world, the safety profile is already covered. The description adds genuinely new behavior: the hard one-organization scoping rule and the requirement to reauthorize to see a different org. It stops short of describing the returned payload.

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

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

Three tight sentences with no filler, front-loading the resource identity before the scoping constraint and the reconnection instruction. Every sentence 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?

For a zero-parameter read tool this is nearly complete: it explains scope, the no-argument contract, and the limitation on switching orgs. The only gap is that no output schema exists, so the description could have said what fields the organization record actually returns.

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

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

The tool takes zero parameters, which is the baseline 4 case. The description reinforces this with 'Takes no arguments,' removing any doubt, but there is no parameter meaning to add beyond that.

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 specific resource (the Trackberry organization this connection is scoped to) and resolves the plural-name ambiguity by stating that exactly one organization exists per connection. It also implicitly distinguishes itself from siblings, noting every other tool answers about that same organization.

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 explains the context in which the tool is relevant (the connection is scoped to one org and all other tools report on it) and gives an explicit exclusion: you cannot read another org with this tool, you must disconnect and reconnect with a different token. What's not stated is the concrete trigger for calling it (e.g., to obtain the organization id used elsewhere), though that is easy to infer.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond them: it explains what available/allocated/in_transit/arrived mean, how min_qc_score filters pallets and how `excluded` counts dropped boxes, that archived shipments are excluded, and how container numbers and shipment URLs should be used. This is exactly the extra behavioral context annotations cannot carry.

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?

Deliberately front-loaded with the purpose before the field-by-field semantics, and most sentences earn their place. It is dense and long, though — output-field explanation is interleaved with filtering guidance rather than separated, which slightly reduces scanability.

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 describe what comes back, and it does: available_boxes, allocated_boxes, in_transit_boxes, arrived_boxes, qc_score, qc_scored_boxes, min_qc_score/excluded, container_numbers and shipment_url. An agent has enough to call the tool and interpret the result correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: it clarifies min_qc_score semantics (pallet's own score, with a separate `excluded` count), the string-normalisation rule for calibres ("14", "12+", "113"), and the sale-relevance of the arrival buckets. That is more than restating the schema.

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

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

States a precise verb+resource with an explicit scope definition: boxes on live shipments, on the water or landed, not pre-allocated, grouped by produce and calibre. This is specific enough that an agent can tell it apart from shipment/document tools like search_shipments or get_shipment without opening any 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 three concrete example questions that map directly onto the tool (unallocated size 14 avocados in Rotterdam, what can be sold arriving next week, mango sizes with QC 7+), which is strong positive routing. It does not, however, name an alternative tool or state when NOT to use it, 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.

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive) and the description does not contradict them. It adds genuinely useful behavior: archived shipments excluded by default, results are paged with a has_more/starting_after cursor, and the url field must be linked rather than fabricated. Missing only rate-limit or error 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?

Front-loads purpose and scoping in the first sentence, then usage, results, and paging guidance in a logical order. It is dense and long for a search tool, but nearly every sentence carries actionable information rather than filler.

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

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

With no output schema, the description compensates by enumerating the summary result fields (status, route, ETD/ETA, carrier, containers, failed checks, latest_event) and explaining paging and the url contract. Combined with the full schema, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description restates much of what the schema already documents (query matching references/B/L/containers/parties/ports/produce, detail:full, archived default) and adds only marginal detail such as 'use the id for the other tools' and the url linking instruction.

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 (find/search) and resource (shipments), scoped to the organization with a defined order ('newest first'). It explicitly distinguishes itself from siblings get_tracking_timeline and get_shipment, so an agent can route correctly without opening a 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?

Names concrete user questions it answers, gives an explicit when-not ('do not call get_tracking_timeline per shipment for an overview; call it only for one shipment's full history'), and names the alternative for single-shipment needs (get_shipment). Routing is unambiguous.

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