machship-mcp

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation2/5
Many tools have overlapping purposes, such as multiple consignment creation tools (create_consignment, create_consignment_existing_items, create_pending_consignment) and numerous consignment retrieval tools (get_active_consignments, get_all_consignments, get_completed_consignments). Descriptions help but do not fully resolve ambiguity.
Naming Consistency5/5
All tools follow a consistent 'machship_verb_noun' pattern (e.g., machship_create_consignment, machship_get_company_carriers). Verbs are uniformly imperative and nouns are clear, making the naming predictable and easy to navigate.
Tool Count2/5
With 125 tools, the server is overly large for typical MCP use. Many tools could be combined (e.g., multiple get consignments variants) or are redundant, leading to clutter and decision fatigue.
Completeness4/5
The server covers a wide range of freight management operations including consignment lifecycle, quotes, carriers, manifests, items, identities, and documents. Minor gaps exist (e.g., no explicit delete for quotes), but overall the surface is comprehensive.
Average 3.8/5 across 110 of 125 tools scored. Lowest: 2.8/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 10 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
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?
Annotations indicate it's not read-only, not destructive, not idempotent, but the description does not elaborate on side effects, success/failure behavior, or retry safety. Minimal behavioral disclosure beyond the annotation flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence and an args list; not verbose but could be more compact. The structure is functional but lacks front-loading of key 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?
No output schema and no description of return value. The complex nested parameter 'body' lacks detailed subfield documentation. Context about what the tool returns or when it's appropriate 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?
Single parameter 'body' with vague description in schema. The description adds 'carrierInvoiceId, etc.' hinting at required fields, but the schema allows any additional properties. Schema coverage is 100% but lacks structural detail.
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?
Description states 'Attempts automatic reconciliation of carrier invoices' which is a clear verb+resource. However, it does not distinguish from sibling tools like get_carrier_invoices or get_carrier_invoice_entries.
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 on when to use this tool vs alternatives, nor any prerequisites or conditions. The description lacks context about when auto reconciliation is applicable.
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?
Annotations declare non-read-only and non-destructive, but the description does not add details like idempotency, error handling, size limits, or effects on existing attachments. The agent lacks critical behavioral context for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but includes a redundant 'Args' section that largely duplicates the schema. It could be more concise by omitting the parameter details already present in the schema.
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 has no output schema, and the description omits any return value information. For an upload operation, the agent needs to know what to expect (e.g., success confirmation, attachment IDs). This is a significant 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 coverage is 100%, so the description adds marginal value beyond repeating parameter names. The 'Args' section provides a structured view but no new semantic information (e.g., file size limits, encoding requirements).
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 states it uploads one or more attachments, distinguishing it from retrieval tools like get_attachment and get_consignment_attachments. However, it doesn't explicitly differentiate from upload_commercial_invoice, which may cause confusion.
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 provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, limitations, or use cases. The agent must infer usage from the parameter list alone.
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?
Annotations indicate readOnlyHint=false and destructiveHint=false, implying a safe write operation. The description adds 'Edits an existing...' but doesn't clarify whether it's a full replacement or partial update, or the return value. Little behavioral detail beyond 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 short and straight to the point with one sentence and an args list. No extraneous text. Could be slightly expanded for context, but efficient.
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 write operation with no output schema, the description lacks error conditions, side effects, or response details. The agent is left guessing about the behavior and results, making it incomplete.
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% with a description for the 'location' parameter. However, the description just reiterates the schema ('Updated location data including id') without adding constraints, valid fields, or format details. 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 title and description clearly state the action is editing a company location. The verb 'Edits' and resource 'company location' are specific. Siblings include create and get variants, making the update purpose clear, though not explicitly differentiated.
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 on when to use this tool vs alternatives like create_company_location or get_company_location. No prerequisites or exclusions mentioned. The agent must infer usage from the tool name alone.
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?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safe read nature is clear. However, the description adds no additional behavioral context beyond what annotations imply. It does not discuss potential errors, rate limits, permissions, or the shape of the response. With annotations present, the description fails to add value.
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 very short: one sentence plus an args list. It is not verbose, but the args list is redundant given the schema. However, it is still appropriately sized and front-loaded. It could be more concise by removing the args list, but it earns its place.
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 simple get tool with one parameter and no output schema, the description is incomplete. It does not mention the return format (e.g., list of identity providers), any ordering, or pagination. The annotations cover safety, but the description fails to provide enough context for an AI to fully understand the tool's 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?
Schema coverage is 100%, and the description merely restates the parameter name and type ('companyId (number): Company ID'). It adds no new meaning beyond what the input schema already provides. Baseline 3 is appropriate as the schema does the heavy lifting.
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 states the purpose: 'Get all identity providers associated with a specific company.' It uses a specific verb and resource. However, it does not differentiate from sibling tools like 'machship_get_identity_providers_for_logged_user' and 'machship_get_identity_providers_for_organisation', which have very similar names and purposes.
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 provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, when not to use it, or contrast with similar tools. Given the existence of sibling tools for different contexts (logged user, organisation), this is a significant omission.
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?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, indicating a safe read operation. The description adds nothing beyond 'Returns locations' and does not disclose any behavioral traits such as pagination, error handling, or what happens with invalid options. With annotations present, the bar is lower but the description still fails to add meaningful context.
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 very short and to the point, consisting of a single line and a parameter list. While it lacks structure (e.g., bullet points), it is concise and front-loaded, with no unnecessary information.
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 only two parameters, no output schema, and annotations cover safety, the description is minimally adequate. However, it does not specify the return format, any limitations, or how the 'options' object is processed. It leaves questions like valid option keys unanswered, but for a simple read tool, it is functional.
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% with both parameters described. The description adds minimal value, essentially mirroring the schema with a slight expansion for 'options' listing country and state. Baseline 3 is appropriate as the schema already provides adequate meaning.
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 states that the tool returns locations with search options/filters. It distinguishes itself from other location tools through the 'options' parameter for flexible filtering, but does not explicitly mention how it differs from siblings like 'machship_search_locations' or 'machship_get_locations_exact'.
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 on when to use this tool versus alternative location-fetching tools. The description lacks any context about ideal use cases, prerequisites, or exclusions, leaving the agent to infer applicability.
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?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds no further behavioral context beyond confirming it's an additive mutation. No mention of side effects, auth requirements, or error conditions.
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 concise (two sentences) with no wasted words. However, it could be more informative by incorporating usage cues without increasing length significantly.
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 tool that creates permanent schedules with a nested object parameter, more detail is needed about schedule format, expected behaviors, and response. The description is too sparse given the 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 100% for the single 'payload' parameter. The tool description aligns but adds minor detail about 'pickup schedule details'. Baseline 3 is appropriate since the schema already covers the parameter meaning.
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 ('Adds') and resource ('permanent scheduled pickups to a company location'), clearly distinguishing it from sibling tools like machship_get_permanent_pickups (retrieval) and machship_edit_company_location (editing).
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 on when to use this tool versus alternatives, prerequisites (e.g., existence of company location), or when not to use it. The description leaves the agent without context for invocation decisions.
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?
Annotations indicate a write operation, but description adds no extra behavioral context like validation, idempotency, or error conditions. Minimal value beyond 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?
Two efficient sentences with a clear purpose and parameter list. No fluff, front-loaded correctly.
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?
Simple tool but lacks details on required subfields, expected response, and prerequisites. Not fully self-contained for an agent to use 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% and description lists fields, but largely repeats schema info. Decent but does not add significant meaning beyond what's already provided.
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 clearly states 'Creates a new company location' with specific subtypes and distinct verb, differentiating from sibling tools like edit and get.
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 on when to use this tool versus alternatives such as edit_company_location or other creation tools. Lacks when/when-not criteria.
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 non-read-only, non-destructive, and non-idempotent. The description adds 'manually' and an example, but does not disclose side effects like whether statuses are appended or overwritten, or any restrictions on status values. It adds marginal value beyond 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 very short and efficient, with one sentence and a bullet-like list. It avoids fluff, but the structure could be improved (e.g., separating purpose from parameters). Still, it earns its place.
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 description lacks details about return values (no output schema), how statuses are applied (overwrite vs append), and any validation on status values. Given the mutation nature, more behavioral context is needed, making it incomplete.
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%, so the description's mention of sub-parameters is redundant. The example 'e.g. mark as delivered' hints at a valid status but does not add constraints or meaning beyond the schema's minimal descriptions. It meets the baseline but adds little extra value.
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 the tool manually updates tracking statuses, using verb 'updates' and resource 'tracking statuses' with an example. This clearly conveys the action but does not explicitly differentiate from sibling tools like 'edit_consignment' that might also modify consignment fields.
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 on when to use this tool versus alternatives. There is no mention of when not to use it or which sibling tools cover related operations (e.g., get_consignment_statuses for reading, edit_consignment for other updates).
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 annotations already declare destructiveHint: true, so the description adds nothing beyond what is already known. It does not disclose any additional behavioral traits such as irreversibility, permission requirements, or 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, with no wasted words. However, it could add a sentence about the scope or effect without sacrificing brevity.
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 delete operation with one parameter and no output schema, the description is minimally adequate. However, it lacks information about permanence, error conditions, or what happens after deletion.
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%, so the description of the 'ids' parameter in the tool description repeats the schema's description. No additional meaning is added 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 states the action 'Deletes' and the resource 'one or more pending consignments', distinguishing it from the sibling tool 'machship_delete_consignments' which deletes actual consignments.
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 provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. The distinction from 'machship_delete_consignments' is implied by the name but not explicitly 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 indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it returns a PDF and clarifies the relationship between consignment and manifest, which is useful but not essential beyond 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 very concise with two short sentences. It is front-loaded with the main purpose. The 'Args' line is acceptable but could be integrated more naturally.
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 retrieval tool with one parameter and no output schema, the description is adequate. It explains what is returned and the input. It does not cover edge cases, but given the annotations and simplicity, it is sufficiently 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?
The schema covers 100% of parameters with descriptions. The description's 'Args' section merely repeats the schema info ('Consignment ID') without adding new meaning or constraints.
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 states the action ('Returns') and resource ('manifest PDF') and links it to a consignment. However, it does not differentiate from a sibling tool like 'machship_get_manifest_label_pdf' which might get the same PDF by manifest ID directly.
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 on when to use this tool versus alternatives (e.g., 'machship_get_manifest_label_pdf' or 'machship_get_consignment_label_pdf'). The description lacks context about prerequisite conditions or exclusions.
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's 'Searches' aligns without contradiction. The description adds context on search fields but does not detail result format, pagination, or other behavioral traits beyond what annotations 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 concise (two sentences plus Args) with front-loaded purpose. It efficiently conveys the tool's function without unnecessary words.
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 simple single-parameter tool with rich annotations, the description adequately covers the search intent. However, it lacks details on the return values (e.g., consignment fields) and assumes output format, leaving some ambiguity for a search 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?
Schema coverage is 100% with a clear description of 'references'. The description adds minimal extra meaning by specifying the array of reference strings and the search fields, but essentially restates the schema. 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 clearly states the verb 'Searches' and the resource 'consignments', specifying search by reference numbers (Reference 1, Reference 2, or carrier IDs). It distinguishes from sibling tools like get_consignments_by_reference1 by offering a combined search, but could explicitly differentiate.
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 explicit guidance on when to use this tool versus alternatives like machship_get_consignments_by_reference1 or machship_get_consignments_by_reference2. The description implies usage for reference searches but does not provide when-not-to-use or compare to siblings.
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 this is a write operation (readOnlyHint=false) and non-destructive. The description adds that the consignment is unmanifested, but does not disclose side effects, auth requirements, or other behavioral traits beyond what annotations imply.
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 a bullet list of args. Front-loaded with purpose. No redundant information, but could be more structured with required vs optional fields.
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?
Lacks information on return values (no output schema) and error conditions. For a core booking operation, agents need to know what is returned upon success or failure. Does not mention idempotency or state changes beyond creation.
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?
While schema coverage is 100%, the description adds value by listing expected sub-fields (toAddress components, items structure, references) that are not in the schema description. This helps agents understand typical consignment structure, though optionality is not specified.
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 states it creates a new unmanifested consignment and is the core operation for booking freight. It specifies the verb and resource, but does not explicitly differentiate from sibling creation tools like create_pending_consignment or create_consignment_existing_items.
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 on when to use this tool versus alternatives such as create_pending_consignment or create_consignment_with_complex_items. Lacks prerequisites, exclusions, or typical 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=true and destructiveHint=false. The description adds the 'max 100 records per call' limit, which is a useful behavioral constraint. However, it does not clarify what 'basic information' includes or if there is any pagination mechanism beyond the limit.
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 concise: one sentence stating the purpose and limit, followed by a clear list of optional parameters. Every part is necessary, and the key info is front-loaded.
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 4 optional parameters, no output schema, and annotations present, the description covers the main points: purpose, filter parameters, and record limit. However, it lacks details on default behavior (e.g., what happens if no filters are provided), sorting, or whether the 100 record limit implies pagination. It feels minimally adequate but not comprehensive.
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 description's Args section largely duplicates the schema's parameter descriptions. It adds no additional semantics beyond what the schema provides, so 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 clearly states it returns basic carrier invoice information with a max 100 record limit. It uses a specific verb-resource combination. However, it does not explicitly differentiate from the sibling tool 'machship_get_carrier_invoice_entries', though the tool name itself is distinctive.
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 lists filter parameters but provides no guidance on when to use this tool versus alternatives like 'machship_get_invoice_by_document_number' or 'machship_get_posted_invoices'. There is no mention of when not to use it or recommended contexts.
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 strong behavioral cues (readOnlyHint=true, destructiveHint=false, idempotentHint=true). The description adds only that it retrieves by ID, which is consistent but adds no extra behavioral context (e.g., what happens if ID not found).
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?
Extremely concise: two sentences that front-load the purpose and list the parameter. No redundant phrases.
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 extensive sibling list, the description is minimal. It omits any mention of return value or error handling. While the schema is rich, the tool would benefit from stating that it returns a single identity provider object.
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 covers 100% of parameters with a description identical to the description's mention. The description does not add any new meaning beyond the schema, so baseline score applies.
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 states 'Get a specific identity provider by ID', which is a specific verb+resource. It distinguishes from sibling list tools (e.g., machship_get_identity_providers_for_company) by focusing on a single provider retrieval, though it could explicitly differentiate.
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 on when to use this tool versus alternatives. With many similar identity-related tools (e.g., machship_get_identity, machship_get_identity_providers_for_company), the description should hint at appropriate contexts but does not.
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 readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds the constraint 'Max 10 per request', which provides useful behavioral context beyond annotations. However, it does not explain what 'pending' means or describe any additional behavior like ordering or error handling.
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 extremely concise: two sentences plus a parameter listing. Every sentence provides essential information without any redundancy.
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 with one parameter and full schema coverage. However, no output schema exists, and the description does not clarify the return format (e.g., list of consignment objects). It mentions 'finds' but not what is returned, 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter 'references', including its type, constraints, and description. The description repeats this information but adds no new semantic meaning beyond what the schema already states.
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 states the tool finds pending consignments by the Reference 2 field using a specific verb ('finds'). It distinguishes from siblings like get_consignments_by_reference2 by specifying 'pending' consignments, but does not explicitly contrast with get_pending_consignments_by_reference1, relying on the name for differentiation.
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 use this tool versus alternatives (e.g., get_pending_consignments_by_reference1, get_consignments_by_reference2). No exclusions or context indicating when to avoid or prefer this tool are provided.
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?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, indicating safe read. The description adds that it returns 'pending consignments' and uses UTC date range, but does not disclose pagination behavior, defaults, or response format. Given annotations cover the safety profile, this adds minimal 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loads the main purpose, and uses a clear Args list. Every sentence adds value. It could be slightly more structured but is efficient overall.
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 8 parameters, no output schema, and a sync use case, the description lacks details on pagination behavior (e.g., zero-based index, max page), response structure, or potential rate limits. This makes it incomplete for a complex retrieval 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?
Schema description coverage is low (38%), so the description must compensate. It lists all 8 parameters with brief descriptions like 'Pagination start' for startIndex, but does not add details like default values, bounds, or behavior beyond the schema. This is a marginal improvement over 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 'Returns pending consignments created or updated within a UTC date range. Useful for sync workflows.' This clearly identifies the tool's purpose and distinguishes it from sibling tools like machship_get_pending_consignment (single) and machship_get_recent_consignments (non-pending).
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 mentions 'Useful for sync workflows,' providing some context, but lacks explicit guidance on when not to use this tool or alternatives among the many get-consignment tools. No exclusions are specified.
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?
Annotations provide base info: readOnlyHint=false, destructiveHint=false. The description adds 'Requires administrator access' but does not disclose whether the operation is reversible, what happens if links already exist, or any side effects. Behavioral context beyond annotations is minimal.
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 three sentences, front-loaded with the core purpose. It includes an essential prerequisite. No filler or redundant information.
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 single parameter with nested objects and no output schema, the description provides the core action and required access level. However, it omits return value information and edge case behavior (e.g., duplicate links, partial success). With annotations covering basic safety, 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 coverage is 100% with descriptions for each property. The description repeats the structure but adds no new semantic detail (e.g., role format, constraints). Baseline 3 is appropriate as the description does not significantly enhance understanding 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 states the action: 'Assign companies and roles to identities to give them access to the system.' The verb 'assign' and resource 'identities to companies' are specific. It naturally distinguishes from sibling tools like 'unlink_identities_from_companies' (reverse) or 'get_identities' (read-only).
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 only guidance provided is 'Requires administrator access.' There is no explicit indication of when to use this tool versus alternatives, such as when identities already have links or when to use 'create_identities' instead. No 'when not to use' or comparison with sibling tools is given.
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 indicate a write operation (readOnlyHint=false) and non-destructive behavior. The description adds that merging reduces shipment units but does not detail side effects like state changes to original consignments. 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 concise with three sentences: purpose, benefit, and parameter list. It is front-loaded and contains no wasted words, earning high marks for efficiency.
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 write operation with a complex object parameter and no output schema, the description lacks essential details such as effects on existing consignments, constraints, error handling, and output format. It is insufficient for correct invocation without external knowledge.
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 description specifies that the 'request' parameter includes consignment IDs and consolidation parameters, adding meaning beyond the schema's generic 'Consolidation request payload'. Schema coverage is 100%, but the description provides useful contextual detail.
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 states the tool consolidates consignments into consolidated shipments for carrier efficiency, providing a specific verb and resource. However, it does not differentiate from related sibling tools like machship_group_consignments_for_consolidation, which limits clarity regarding when to use this exact tool.
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 does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites (e.g., consignments must be grouped first). It lacks context for proper invocation.
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 this is a write operation (readOnlyHint=false) and not destructive. The description adds that it creates a consignment with complex items, which is consistent with annotations. No further behavioral details (e.g., permissions, side effects) are disclosed beyond the basic create action.
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 extremely concise—two sentences, one for purpose and one for parameter. It uses an 'Args:' label for clarity and contains no redundant 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?
Given the complexity of the consignment object (nested, with dangerous goods), the description is minimal. It does not explain required fields, structure of complexItems, or return format. The openWorldHint true further signals need for clarity that is absent.
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% for the single parameter, so baseline is 3. The description merely repeats the schema description ('Consignment data with complexItems array'), adding no new meaning or constraints beyond what the schema provides.
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 states it creates consignments with complex item definitions, including detailed packaging and dangerous goods data. It distinguishes from siblings like machship_create_consignment by specifying the use of a complexItems array instead of standard items.
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 usage when detailed packaging or dangerous goods are needed, but it does not explicitly contrast with alternatives like machship_create_consignment or machship_create_consignment_existing_items. No when-not-to-use 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 mark the tool as read-only, idempotent, and non-destructive. The description adds that it returns base64-encoded file content, which is useful beyond annotations. However, it does not disclose potential file size limits or error scenarios.
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 exceptionally concise, consisting of three short sentences with no extraneous information. It is front-loaded with the core action and return format.
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 simplicity (single parameter, no output schema, rich annotations), the description covers the essential function and return format. It could be slightly improved by mentioning typical use cases, but overall it is adequate.
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 provides full coverage (100%) with a description for the 'id' parameter. The description repeats this without adding new meaning, such as how to obtain the attachment ID or the exact expected format.
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 states 'Downloads raw attachment file bytes from Machship by attachment ID', specifying the verb (downloads), resource (attachment file bytes), and method (by ID). It distinguishes from siblings like get_attachments_by_consignment_ids and get_consignment_attachments by focusing on a single attachment download, but lacks explicit differentiation.
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 on when to use this tool versus alternatives such as get_attachments_by_consignment_ids or get_consignment_attachments. There are no when-to-use, when-not-to-use, or prerequisite clarifications.
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, destructiveHint=false, idempotentHint=true. The description adds minimal incremental value by specifying PDF format, but does not disclose edge cases like missing consignment IDs or response size limits. With annotations present, a 3 is appropriate.
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?
Very concise: two sentences, front-loading the result format. No wasted words, but could be slightly more structured.
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?
Simple tool with one parameter, annotations, and no output schema. Description is adequate but does not clarify potential variations (e.g., whether base64 or bytes depends on some context). Lacks completeness for a full understanding.
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% with one integer parameter. The description repeats the parameter name and type ('consignmentId (number): Consignment ID') without adding extra meaning beyond the schema. Baseline 3 is correct.
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 it returns a consignment label as a PDF, specifying the format (base64 or file bytes). It distinguishes from sibling tools like machship_get_item_label_pdf by targeting consignment labels specifically.
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 on when to use this tool versus other label retrieval tools (e.g., machship_get_item_label_pdf, machship_get_manifest_label_pdf). The agent receives no context about prerequisites or alternative choices.
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, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds no extra behavioral context (e.g., what happens if the ID does not exist). With annotations covering safety, the description is adequate but not enhanced.
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 short (two sentences) and direct, but the second sentence redundantly restates parameter details already present in the schema. It could be more efficient by omitting the parameter list.
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 retrieval tool with good annotations and a single parameter, the description is mostly sufficient. However, it does not mention what the response contains (e.g., the full schema object), which could be improved for completeness.
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 description repeats the parameter info ('id (string): The DotNet class ID of the schema') without adding new semantics. 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 states the action ('Returns a specific custom schema by its DotNet class ID'), specifying both the verb and the resource. It distinguishes from sibling tools like 'machship_get_custom_schemas' (plural), which retrieves all schemas.
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 explicit guidance on when to use this tool versus alternatives, such as when to use 'machship_get_custom_schemas' instead. The context for use is implied 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 declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds no additional behavioral context (e.g., authentication requirements, error behavior). It is consistent but not additive.
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 very concise with one clear sentence plus a parameter list. No unnecessary words. However, it could be slightly more informative without being 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?
The tool is simple with one parameter and no output schema. The description is minimal but sufficient for a basic retrieval operation. However, it lacks any indication of what the response contains (e.g., identity details), which could be helpful for an AI agent.
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 describes the 'id' parameter with 100% coverage. The description only repeats the parameter name and type, adding no new meaning beyond what the schema provides. Baseline 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?
Description clearly states 'Get the identity with the given ID.' It uses a specific verb ('Get') and resource ('identity'), and the singular form distinguishes it from sibling tools like machship_get_identities (list) and machship_update_identity (update).
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 on when to use this tool versus alternatives (e.g., machship_get_identities for listing, machship_update_identity for updating). The description does not provide context for selecting this tool over siblings.
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, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds that the tool returns dimensions, which goes beyond annotations but is minimal. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and front-loaded with the core purpose. It is efficient with no wasted words, though it could be slightly expanded.
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 get-by-ID tool with one parameter and no output schema, the description covers basic purpose and parameter. However, it lacks details about the exact structure of the returned item, possible error conditions, or any additional context that might be helpful. Annotations compensate somewhat.
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 schema already describes the 'id' parameter with 'Item ID'. The description merely restates this, adding no new meaning. Baseline is 3 given 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 the tool returns a single saved item (product/SKU) with dimensions by ID. It uses a specific verb ('returns') and resource ('single saved item'), and distinguishes from sibling tools like 'machship_get_items' (plural) and 'machship_get_item_by_sku' (by SKU).
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 provides no guidance on when to use this tool versus alternatives such as 'machship_get_item_by_sku' or 'machship_get_item_complex'. It does not 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, destructiveHint, idempotentHint, openWorldHint. Description adds that it returns 'detailed dimensions' but nothing contradictory; it provides minimal behavioral context 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?
The description is efficient with one sentence and a structured Args list, though the Args list is redundant with the schema. No unnecessary text.
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?
Lacks detail on the return format or structure beyond 'complex item (detailed dimensions)'. Given no output schema, a bit more context would help, but annotations cover the safety profile adequately.
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 schema already describes companyId and sku. The description's Args block repeats this information without adding new semantics like format or examples, but it structures the parameters for quick reference.
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 it returns a complex item (detailed dimensions) by SKU for a company, distinguishing it from siblings like get_item_complex (without SKU) and get_item_by_sku (possibly non-complex).
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 explicit guidance on when to use this tool vs alternatives such as machship_get_item_complex or machship_get_item_by_sku, despite a large set of sibling get-item tools.
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 readOnlyHint=true and destructiveHint=false, so the description adds only the fact that the output is a PDF. It does not disclose potential failure scenarios (e.g., if consignment has no MO41 document) or any other behavioral details beyond what annotations 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 extremely concise: two sentences, no fluff. The first sentence clearly states the primary purpose, and the second enumerates the required argument. All content is relevant and front-loaded.
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 low complexity (single parameter, no output schema) and informative annotations, the description is minimally adequate. However, it lacks details on error conditions (e.g., missing MO41 document) or whether the PDF is returned as binary or URL.
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 only parameter, consignmentId, is described identically in both the tool description and input schema ('Consignment ID'). Since schema coverage is 100%, the description adds no new semantic value. It merely repeats existing information.
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 returns the MO41 document PDF for a consignment, specifying the verb 'Returns' and the resource 'MO41 document PDF'. It distinguishes from sibling tools like get_consignment_label_pdf or get_dangerous_goods_pdf by its specific document type.
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 on when to use this tool versus alternatives (e.g., other PDF retrieval tools like get_consignment_label_pdf). There is no mention of prerequisites, when-not-to-use, or alternative methods.
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 readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds no new behavioral traits beyond stating it is a retrieval operation. It does not contradict 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 very concise, two sentences plus an arg list. It is front-loaded with the main purpose. Minor improvement would be better formatting (e.g., using a list).
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 read operation with one parameter and no output schema, the description covers the purpose and parameter. However, it does not describe the return value (e.g., format or contents of pickups), which would be helpful for completeness.
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 is companyLocationId, and its schema description is already 'Company location ID'. The description repeats this in 'Args:' but adds no additional meaning. With 100% schema coverage, baseline is 3.
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 it retrieves all permanent scheduled pickups for a company location. The verb 'gets' and resource 'permanent pickups' are specific, and the title reinforces this. It distinguishes from sibling 'machship_add_permanent_pickups' which does the opposite.
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 explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, when not to use, or compare with similar tools. The only hint is the parameter requirement.
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?
Annotations already indicate it's a mutation (readOnlyHint=false) and not destructive. Description adds no extra context about side effects, error conditions, or what happens on success/failure.
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?
Extremely concise: three lines with main action and parameters. No fluff, front-loaded, efficient.
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 update tool with two fully documented parameters and no output schema, the description is adequate. Could mention that it replaces the entire schema definition, but overall sufficient.
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%, so description repeating parameter info adds marginal value. No additional constraints or behavior details beyond 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?
Description clearly states it updates an existing custom schema using its DotNet class ID. Verb and resource are specific, and it distinguishes from create/delete 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?
No guidance on when to use this tool versus alternatives like create_custom_schema or delete_custom_schema. No prerequisites or exclusions 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 discloses that the tool creates an item, which is consistent with annotations (readOnlyHint=false). However, it does not add behavioral context beyond what annotations imply, such as required permissions, side effects (e.g., database write), or limits (e.g., SKU uniqueness). Annotations already hint at mutability and non-destructiveness, so the description adds minimal extra value.
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 very concise: one sentence stating the purpose and a bullet-like Args section. It front-loads the main action and uses minimal words, earning its place without fluff.
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 basics of what the tool does and its two parameters, but lacks important context like return value (no output schema), error conditions, prerequisites (e.g., company must exist), or behavior on duplicate SKU. For a creation tool with a nested object, more detail would be beneficial, but the description is minimally adequate.
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 baseline is 3. The description repeats parameter details from the schema but adds slight context: for companyId, 'to create item under' and for item, lists example fields like 'sku, description, weight, dimensions'. This adds value beyond the schema, but not extensively.
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 title and description clearly state the tool creates a 'complex item (product/SKU with detailed packaging info)' for a company. The verb 'creates' and resource 'complex item' are specific, and it distinguishes from sibling tools like 'get_item_complex' and 'delete_item'.
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 provides no guidance on when to use this tool versus alternatives such as 'machship_create_consignment_with_complex_items' or 'machship_get_item_complex'. There is no mention of prerequisites or conditions that favor this tool over others.
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, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds minor context (locations types: warehouses, stores, depots) but does not disclose any additional behavioral traits beyond what annotations 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 extremely concise: two sentences stating the purpose and listing the argument. No unnecessary words or repetition. It is front-loaded with the core functionality.
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 read tool with one parameter and no output schema, the description is mostly complete. However, it fails to describe the return format or any pagination behavior, leaving the agent without information on what the response structure looks like. Given the low complexity, a 3 is adequate.
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% as the schema describes the single parameter 'companyId' with description 'Company ID'. The description repeats this exactly without adding extra meaning, format, or examples. Baseline 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 clearly states it returns 'all locations' for a given company, specifying the resource (locations) and action (return). It distinguishes from the sibling tool 'machship_get_company_location' which likely returns a single location, by explicitly using 'all'.
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 provides no guidance on when to use this tool versus alternatives like 'machship_get_company_location' or 'machship_search_locations'. It does not mention prerequisites, when not to use, or any context for selection.
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 read-only, idempotent, non-destructive behavior. The description adds no additional behavioral context (e.g., prerequisites like consignment having dangerous goods, or that PDF is generated). Does not contradict 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?
Very short and front-loaded; one sentence plus a parameter list. Efficient but could be slightly improved with a more structured format.
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 tool with one parameter and no output schema, the description is mostly complete. It lacks mention of error cases or return format, but overall sufficient.
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 already describes the single parameter (consignmentId) with full coverage. The description merely repeats the schema info with no added meaning beyond what the schema 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 'Returns the dangerous goods declaration document PDF for a consignment,' which is specific to the resource (dangerous goods PDF) and distinguishes it from sibling tools like get_attachment or get_commercial_invoice_pdf.
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 on when to use this tool versus alternatives. With many sibling PDF tools, explicit context for when this is appropriate is missing.
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, destructiveHint=false, idempotentHint=true, so the agent knows it is a safe, idempotent read. The description adds the optional PDF download behavior, which is useful but does not reveal any additional side effects or constraints 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 extremely concise: two sentences plus bullet-pointed parameters. It is front-loaded with the core purpose and immediately provides necessary parameter details. No extraneous information.
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?
No output schema is provided, yet the description does not describe the structure of the returned financial invoice beyond the optional PDF download. For a simple retrieval tool, it is minimally sufficient but lacks details about response fields, which would help the agent understand what to expect.
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%, so the input schema fully documents both parameters with descriptions. The description repeats this information without adding extra semantic meaning (e.g., format, constraints, or examples). Baseline score 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 clearly states the action: 'Returns a specific financial invoice by document number, with optional PDF download.' It specifies the resource (financial invoice) and the unique identifier (document number), distinguishing it from other get_ tools like get_consignment or get_posted_invoices.
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 on when to use this tool versus alternatives such as get_posted_invoices or get_carrier_invoices. The description does not mention exclusions or context for selection, leaving the agent without comparative direction.
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, destructiveHint=false, idempotentHint=true, openWorldHint=true, so the safety profile is clear. The description adds that output is a zip file and limit of 40 consignments, but lacks details on error behavior for invalid IDs. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with a clear one-paragraph summary plus an Args list. Front-loads the main purpose. The Args list is somewhat redundant with the schema but not overly verbose.
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 batch retrieval tool with 3 parameters and annotations present, the description is adequate. It covers the core behavior and constraints. Missing details like error handling, but overall complete for the complexity level.
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 description's Args section repeats schema descriptions almost verbatim. No additional meaning beyond the schema, so baseline score 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 clearly states it gets item labels as a zip file for up to 40 consignments. It distinguishes from sibling tools like `machship_get_consignment_label_pdf` and `machship_get_item_label_pdf` by specifying batch retrieval and zip output.
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 does not provide explicit guidance on when to use this tool versus alternatives (e.g., single label PDF tools). It only implies a batch scenario via the max 40 consignments, but no context for 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, so the safety profile is clear. The description adds pagination details and size limits, which supplement the annotations adequately. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence explaining the action followed by a structured parameter list. Every sentence serves a purpose, and it is front-loaded with the core function.
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 the description covers input and pagination well. However, since there is no output schema, the description should ideally specify the return structure (e.g., an array of complex items). The absence of this information 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?
The input schema covers all parameters with descriptions (100% coverage). The description restates the schema's parameter info without adding new meaning, so it meets the baseline but does not enrich understanding.
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 returns a paginated list of complex items for a company, with a maximum of 200 per request. This distinguishes it from sibling tools like get_item_complex (single item) and get_items (non-complex items).
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 provides no guidance on when to use this tool versus alternatives. Given the large number of sibling tools, explicit usage context would be very helpful but is absent.
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, so the description's statement 'Returns available routes' is consistent but adds no new behavioral traits. It does not mention authorization needs, rate limits, or error handling for invalid dangerous goods classifications.
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 exceptionally concise with two short sentences and a clear args listing. Every part adds value without verbosity.
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?
Despite good annotations, the description is incomplete for a tool handling hazardous items. It lacks return value description, error cases, or prerequisites (e.g., item credentials). The large number of sibling tools suggests more differentiation would help.
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 description adds no meaningful detail beyond the schema. It repeats 'complexItems (dangerous goods, specialised packaging)' but does not clarify the structure or required fields within the request object.
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 title and description clearly state the tool returns available routes for shipments with complex items (dangerous goods, specialised packaging). It distinguishes from siblings like machship_get_routes and machship_get_routes_batch by specifying the complex item handling.
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 does not provide guidance on when to use this tool versus alternatives (e.g., machship_get_routes for simple items or machship_get_routes_batch for batch requests). No contextual cues or exclusions are given.
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 readOnlyHint=true and destructiveHint=false, and the description does not add further behavioral context (e.g., side effects, permissions, or groups format). 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 concise with one sentence and a parameter list, front-loading the essential purpose without extraneous 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?
While the description covers the main action, it lacks explanation of what 'print groups' are or what the return value contains. With no output schema, more detail on the response would improve completeness.
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 description's parameter documentation ('Consignment IDs to group for printing') adds no meaning beyond the schema's 'Consignment IDs'.
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 ('groups consignments') and the purpose ('for batch label printing'), differentiating it from sibling group tools like those for manifest or consolidation.
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 on when to use this tool versus alternatives such as machship_group_consignments_for_manifest or machship_group_consignments_for_consolidation.
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 provide basic info (not read-only, not destructive), and the description adds that labels are sent to a 'configured printer', implying a prerequisite. However, it does not disclose error states, what happens if printer is missing, or the response 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?
Two sentences, no filler. The main action is stated first, followed by an args list. Efficient and front-loaded.
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 one-parameter tool with no output schema, the description covers the basics. But it lacks usage context and behavioral detail, making it minimally viable but not comprehensive.
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% with a brief description of the 'requests' parameter, and the tool description echoes it. However, the schema defines items as objects with no structure, so the description adds little beyond stating field names. Baseline 3.
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 'sends labels directly to a configured printer', using a specific verb and resource. It distinguishes from sibling tools like get_label_pdf which retrieve files rather than send to printer.
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 on when to use this tool versus alternatives like get_consignment_label_pdf or group_consignments_for_printing. No prerequisites or exclusions 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 indicate it's not read-only, not destructive, and not idempotent. The description adds that it triggers repricing, but lacks details on side effects, validation, or safety of repeated execution. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the key action and use case. The 'Args:' line adds parameter info efficiently. Could benefit from clearer structure or bullet points.
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 description lacks details on return values, error conditions, or how to retrieve updated results. The parameter body is unspecified, requiring the agent to guess its structure. Given the complexity and absence of output schema, this is a significant 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?
The schema provides no structure for the 'body' object beyond a generic description. The main description adds hints that the body should include consignmentId and items, but is still vague. With 100% schema description coverage, the baseline is 3, and the description provides marginal improvement.
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?
Description states the tool updates consignment items on a carrier invoice entry and triggers repricing, with a specific purpose of reconciling carrier invoice discrepancies. It distinguishes from sibling update tools like machship_edit_consignment by mentioning the connection to carrier invoices.
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 explicitly says 'Use for reconciling carrier invoice discrepancies', providing clear context for when to use this tool. However, it does not mention when not to use it or list alternative tools for similar operations.
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 indicate non-destructive and non-read-only behavior, which aligns with 'disable'. However, the description does not clarify reversibility or side effects beyond login prevention. With annotations present, the description adds only minimal 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?
Extremely concise: two sentences, no filler. The purpose is stated in the first sentence, making it easy for an agent to quickly understand the tool.
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 tool with one parameter and no output schema, the description is sufficient. It could optionally mention reversibility (e.g., 'reenable'), but is otherwise 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?
The input schema has 100% description coverage, so the baseline is 3. The description restates the parameter but adds no new semantic information 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 uses a specific verb 'disable' and resource 'identities', clearly stating the effect 'preventing them from logging in'. It distinguishes from siblings like 'reenable' and '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?
No guidance on when to use this tool versus alternatives (e.g., delete identities, reenable). No mention of prerequisites, such as whether identities must be active 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, destructiveHint, idempotentHint, and openWorldHint. The description adds the maximum request limit but does not elaborate on error handling, pagination, or response behavior.
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 brief with two sentences and an inline args list. It is well-structured and contains no unnecessary information, but could benefit from more explicit formatting.
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 low complexity (one parameter, no output schema), the description provides the essential operation and constraint. However, it lacks details on return values or potential errors, which would be helpful without an 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?
Schema coverage is 100% with a description that already explains the parameter. The description ('Array of Reference 2 values (max 10)') adds no new 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 'Finds' and resource 'consignments by their Reference 2 field', clearly distinguishing from sibling tools like those for reference1 or IDs.
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 states the max limit of 10 references but does not provide explicit guidance on when to use this tool versus alternatives like search_consignments or other get methods.
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, destructiveHint=false, idempotentHint=true, which cover safety and idempotency. The description adds the behavioral trait that it returns 'all' identity providers (a complete list for the organisation), but does not detail any other behaviors like pagination, sorting, or permissions. With strong annotation coverage, a score of 3 is appropriate as the description adds some value beyond 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 extremely concise with two short sentences that get straight to the point. It is front-loaded with the purpose, and every word adds value. No unnecessary elaboration.
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 simplicity (one parameter, no output schema, lightweight behavioral profile), the description covers the core functionality. The annotation set is rich, so the description does not need to elaborate on return values. The sibling context might cause confusion, but the purpose is clear enough for a get-all tool. A minor gap is not explaining that the result is a list, but this is implied.
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 schema already describes 'organisationId' as 'Organisation ID'. The description merely repeats this in the Args section without adding new context, syntax, or format details. According to guidelines, baseline is 3 when schema coverage is high, and no additional meaning is provided.
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 ('Returns all identity providers') and the resource ('for the specified organisation'). It distinguishes from sibling tools like machship_get_identity_provider (singular), machship_get_identities (different resource), and other organization/user-specific variants, making the tool's 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 Guidelines2/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 versus alternatives such as machship_get_identity_providers_for_company or machship_get_identity_providers_for_logged_user. It does not mention any prerequisites, limitations, or exclusion criteria, leaving the agent to infer context from sibling names alone.
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?
Annotations already provide readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, covering the safety profile. The description adds no extra behavioral context (e.g., no mention of null returns, caching, or permissions). It does not contradict annotations but also does not enrich 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?
The description is extremely concise (two sentences), front-loaded with the main action, and lists parameters in a clear list format. No redundant or unnecessary 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 simple read-only tool with fully documented schema and annotations, the description provides adequate information. It does not mention return format (e.g., object or null), but given the lack of output schema and low complexity, this is acceptable. Could specify that the item may not exist, but overall complete enough.
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%, with both parameters having descriptions. The description repeats the parameter names and types without adding new meaning (e.g., format, constraints, or examples). Baseline 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 clearly states it returns a saved item matching a given SKU for a company, using specific verb 'Returns' and resource 'saved item'. It distinguishes from siblings like get_item (by ID) and get_items_by_skus (multiple items), as the name and scope are specific.
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 guidance on when to use this tool versus alternatives like get_item or get_items_by_skus. The description implies it's for a single item by SKU, but does not state exclusions or comparison with other tools.
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, destructiveHint=false, idempotentHint=true, so safety is clear. The description adds no additional behavioral context beyond what annotations provide, which is adequate but does not go further.
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 extremely concise with two brief sentences. Essential information is front-loaded. No unnecessary words or 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 the tool's low complexity (single parameter, no output schema, strong annotations), the description provides enough information to select and invoke correctly. However, it does not explain the concept of a 'pending consignment' or the return format.
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 description repeats the parameter description from the schema. No additional meaning or constraints are added beyond what the input schema already defines.
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 it returns details for a single pending consignment by ID. It uses a specific verb ('Returns') and resource ('pending consignment'), and distinguishes it from siblings that handle multiple IDs.
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 on when to use this tool versus alternatives like machship_get_pending_consignments_by_ids. No exclusions or context about prerequisites or limitations.
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 readOnly=true, destructive=false, idempotent=true, openWorld=true. The description adds behavioral details: it enforces a maximum of 100 invoices per call and supports pagination via startIndex and retrieveSize parameters. This goes beyond the annotations by clarifying limits and pagination 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 concise: a single sentence summarizing the main functionality followed by a clear bullet list of parameters. No unnecessary words. Front-loaded with the 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?
Given the tool has 4 parameters, no output schema, and no explicit return structure, the description adequately covers the input but lacks detail on the output format (e.g., fields of an invoice). However, the tool name and annotations provide some context. It is moderately complete for a simple retrieval tool.
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 50% (startDate and endDate have descriptions in schema, but startIndex and retrieveSize do not). The description compensates by listing all parameters with types, optionality, defaults, and constraints (e.g., ISO 8601 format, max 100 for retrieveSize). This adds meaning beyond the raw 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 clearly states it returns posted financial invoices with an optional date range and a max of 100 per call. The verb 'returns' and resource 'posted financial invoices' are specific. It distinguishes from sibling tools like get_carrier_invoices by specifying 'posted' invoices, though it doesn't explicitly contrast.
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 on when to use this tool versus alternatives (e.g., get_carrier_invoices). There is no mention of prerequisites, exclusions, or best practices. The description only states what it does, not when it is appropriate.
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?
Description adds minimal value beyond annotations. 'Preview before manifesting' aligns with readOnlyHint=true and destructiveHint=false. Description is consistent, but lacks details on scope or 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?
Two-line description with main sentence and args line. Front-loaded, no filler, every sentence is necessary.
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 single-param tool with annotations and no output schema, the description is adequate. Could describe 'manifest groups' outcome format, but not critical for a preview operation.
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 description just repeats the schema's parameter info (companyId: Company ID). No additional semantic meaning provided.
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 title and description clearly state the verb (groups), resource (ALL unmanifested consignments), and outcome (into manifest groups, preview). It distinguishes from the sibling 'group_consignments_for_manifest' by emphasizing 'ALL'.
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?
Implies use before manifesting but does not explicitly state when to use this vs the sibling tool 'machship_group_consignments_for_manifest' for specific consignments. No when-not-to or alternative guidance.
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 a write operation (readOnlyHint false) and non-destructive (destructiveHint false). The description adds that it combines two operations, but does not disclose side effects, required permissions, or whether the operation is reversible. With annotations covering basic safety, the score is moderate.
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 very concise—one sentence and a bullet—with no extraneous words. It front-loads the purpose effectively.
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 combined grouping and consolidation operation, the description lacks information on return values, prerequisites, or concrete parameter structure. No output schema exists, and the parameter description is minimal. This is insufficient for an AI agent to fully understand the tool's behavior and inputs.
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 describes 'options' as an object with no specified properties. The description adds example keys (companyId, carrierId, grouping rules), which provides some semantic guidance, but the parameter remains open and under-specified. With high schema coverage (100%), baseline is 3.
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 groups and consolidates consignments in a single operation, combining two steps. This distinguishes it from siblings like group_consignments_for_consolidation and perform_consolidation.
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 usage by stating it combines grouping and performing, but does not explicitly state when to use this combined tool versus calling the two separate steps. No exclusion criteria or alternatives are listed.
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 write (readOnlyHint false) and non-idempotent. The description adds key effects: creates pickup booking and generates tracking numbers. However, it does not disclose that the operation may fail if carrier is unavailable, potential side effects, or that it is not idempotent. Given annotations cover some safety, the description adds moderate value.
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 concise: two sentences and an Args section. It front-loads the main action. However, it could be more structured by listing effects or prerequisites in bullet points. Nonetheless, it is efficient and clear.
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 one parameter and no output schema, the description covers the primary purpose and parameter. However, it omits return value (e.g., tracking numbers, manifest ID) and error handling. It is acceptable for a simple tool but lacks completeness for a workflow step.
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?
There is one parameter with 100% schema description coverage. The description repeats the schema's explanation ('Array of booked manifest objects with consignment IDs and carrier booking details') but does not add new constraints or examples. It minimally adds 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 clearly states the verb 'Books/manifests' and the resource 'consignments with the carrier', and explains it creates pickup booking and generates tracking numbers. It also explicitly positions it as 'the final step in the consignment workflow', distinguishing it from sibling tools like create_consignment or get_consignments.
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 usage as the final step but does not explicitly state prerequisites (e.g., consignments must be created first) or when not to use it. It also lacks guidance on alternatives or consequences of multiple calls (non-idempotent). The context is partially clear but not thorough.
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?
Annotations indicate a write operation (readOnlyHint=false), but the description does not disclose side effects (e.g., overwrite behavior, state requirements). It only reiterates that files are base64-encoded, which is already in the schema.
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 concise with a clear first sentence and a structured Args list. No extraneous 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 simple upload tool with full schema coverage and no output schema, the description adequately explains the operation and parameters. Minor missing info on return values or post-upload behavior, but acceptable.
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 description merely repeats the parameter names and types. It adds minimal context beyond what the schema provides, so baseline 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 clearly states the tool uploads commercial invoice files for a consignment (international shipments). It distinguishes from siblings like machship_upload_attachments and machship_get_commercial_invoice_pdf.
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 it is for international shipments but offers no explicit guidance on when to use this tool versus alternatives like upload_attachments, nor does it mention prerequisites or when not to use.
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 provide basic behavioral hints (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description does not need to repeat those. However, the description adds no additional behavioral context such as side effects, authentication needs, or error behavior. The transparency is adequate but not enhanced.
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 very concise: two sentences plus a compact list of arguments. It is front-loaded with the purpose and structure, and every word contributes 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 is adequate for a simple creation tool with no output schema. However, it lacks details on return value, error handling, and constraints (e.g., unique name). Given the presence of sibling CRUD tools and modest annotations, additional context would improve agent decision-making.
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%, so baseline is 3. The description merely restates parameter names and types already present in the schema without adding deeper meaning (e.g., validation rules, format, examples). It provides no extra semantic value.
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 custom schema to extend Machship entities with additional fields. The verb 'creates' and resource 'custom schema' are specific, and the purpose distinguishes it from sibling CRUD operations like get, update, and delete.
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 but not explicit. The description states it creates a new schema, but does not provide guidance on when to use this tool versus alternatives, nor does it mention prerequisites or conditions. No alternatives are named.
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 indicate it is a mutation (readOnlyHint=false) and not destructive. The description adds that admin access is required and the grouping constraint, but does not explain return values, error handling, or transactional behavior.
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 concise with a clear purpose statement and a structured list of arguments. It is front-loaded but the args list is lengthy; still efficient given the complexity.
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 description lacks information about return values, success/failure responses, and potential errors. For a creation tool with nested parameters, more details about the outcome are needed.
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% with descriptions for each field. The description reiterates most parameters and adds the grouping context ('All identities must belong to the same...'), providing some additional 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 clearly states the action ('Create identities') and the additional assignment of companies and roles. It specifies constraints like same identityProvider and organisation, distinguishing it from other identity-related tools like update, delete, or link.
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 indicates 'Requires administrator access' and that all identities must belong to the same identityProvider and organisation. This provides context for when to use, though it does not explicitly compare to alternatives.
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 destructiveHint=true. The description adds 'This action is irreversible,' which clarifies permanence beyond annotations. However, it does not mention permissions, side effects (despite openWorldHint=true), or error conditions.
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 succinct sentences with a minimal argument list. Front-loaded with purpose and an important warning. No redundant or extraneous 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?
For a simple one-parameter tool, the description covers the operation but lacks return value information (no output schema). Adequate but could mention success indication or error cases.
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 coverage, the description's parameter info ('companyItemId (number): The ID of the item to delete') mirrors the schema description. No additional semantic value is added 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 states the action ('Deletes a saved item from a company'), with a specific verb and resource. It distinguishes itself from sibling delete tools (e.g., machship_delete_consignments) by focusing on items.
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 on when to use this tool versus alternatives, no prerequisites or when-not-to-use instructions. The description only states what it does, not the context for use.
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, destructiveHint=false, idempotentHint=true, and openWorldHint=true, reducing the burden on the description. However, the description does not elaborate on pagination behavior, default filtering, or time zone implications. It adds some context via parameter names but lacks deeper behavioral disclosure.
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 very concise: one sentence summarizing the function, followed by a structured argument list. Every element is relevant, and the format is easily scannable.
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's complexity (9 parameters, no output schema, many siblings), the description is adequate but not complete. It explains the basic purpose and filtering options but omits details like response structure, pagination defaults, and the behavior of the filterByEtaCompletedOrDespatch parameter.
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 low (33%), but the description compensates by listing all parameters with brief explanations. While not exhaustive (e.g., no enum values for filterByEtaCompletedOrDespatch), it provides meaningful descriptions for each parameter, especially those missing from 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 states the tool returns all consignments for a company with filtering capabilities. It uses a specific verb ('Returns') and resource ('all consignments'), and the 'all' distinguishes it from siblings like get_active_consignments or get_completed_consignments.
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 on when to use this tool versus alternatives. The description does not mention scenarios where other getter tools (e.g., get_active_consignments) would be more appropriate, nor does it provide exclusion criteria.
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, destructiveHint, idempotentHint. Description adds no further behavioral traits like error handling or permissions. With annotations present, description's minimal addition is acceptable but not enhanced.
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-line description with front-loaded purpose and clear parameter listing. No extraneous words.
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?
No output schema, so description should hint at return structure. It says 'returns details' but omits what fields. Adequate for a simple read tool, but could be more 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 coverage is 100% and description rephrases parameter definition ('Company location ID') without adding meaning. Description adds no value beyond 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?
Description clearly states verb 'Returns details for a single company location' and specifies resource types (warehouse, store, depot). Distinguishes from siblings like get_company_locations (plural) and create/edit variants.
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?
Implicit that this tool is for fetching a specific location by ID, but does not explicitly contrast with siblings like get_company_locations for listing or state when to choose this over alternatives.
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?
Description adds context beyond annotations by stating it returns notes including types like internal comments and delivery instructions. Annotations already declare readOnlyHint=true and idempotentHint=true, so no contradiction. Somewhat lacking details on ordering or pagination.
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?
Description is brief and front-loaded with purpose. Slight redundancy in repeating param info, but overall concise and well-structured.
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 tool with one param and no output schema, the description adequately specifies return content. Could mention error handling or if empty notes returned.
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%, so baseline is 3. Description merely repeats schema's param description ('Consignment ID') without adding extra semantic meaning or format details.
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 specific verb 'Returns' and resource 'all notes attached to a consignment', with examples of note types. Clearly distinguishes from many sibling get_*_consignment tools.
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 on when to use this tool vs alternatives. Does not mention that other tools like 'machship_get_consignment' might be more appropriate for core consignment data.
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, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds minimal behavioral context (returning metadata, not downloading). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences plus a parameter list. Front-loaded with the key purpose. No wasted words.
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?
No output schema is present, so the description should clarify what 'file metadata' includes (e.g., filename, size, type). The current description is vague, leaving the agent uncertain about the return value.
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 description repeats the parameter info with minimal additions. Baseline 3 applies as schema already documents the parameters adequately.
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 (returns), the resource (file metadata for item/package label PDF), and the scope (without downloading). It distinguishes from siblings like machship_get_item_label_pdf and machship_get_consignment_pdf_file_info.
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 metadata retrieval as opposed to downloading, but does not explicitly state when to use it over alternatives or provide when-not/alternatives guidance.
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 readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it returns a PDF, but no other behaviors (e.g., response format, size limits) are disclosed. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two lines for arguments) but could explicitly state the return type (PDF) in the first sentence, which it does. It is front-loaded and efficient.
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 no output schema, the description mentions the return type (PDF). It is complete for a simple retrieval tool, though it lacks details on error handling or prerequisites. Annotations cover 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 coverage is 100% with descriptions for both parameters. The description replicates the parameter names and types without adding meaning beyond the schema (e.g., what 'Consignment ID' represents or how to obtain it).
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 returns a PDF of special instructions for a consignment, specifying the resource and its format. It distinctively differs from sibling 'get' tools by targeting a specific document 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?
No explicit guidance on when to use this tool versus others (e.g., get_consignment_label_pdf). The context is implied (retrieve special instructions), but no exclusions or 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?
Annotations already indicate the tool is not read-only (readOnlyHint false) and not destructive (destructiveHint false). The description adds 'restoring login access' as behavioral context, which is helpful but does not disclose side effects or permissions.
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 are concise and front-load the purpose. However, the second sentence is redundant with the schema. Could be slightly tighter by omitting the parameter line.
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 tool with one parameter and no output schema, the description is fairly complete. It states the action and effect. Lacks details on undo behavior or invalid ID handling, but these are minor.
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 description's Args section only restates the schema's description ('Array of identity IDs to re-enable'). No additional meaning or constraints 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 ('Re-enable') and resource ('identities'), and adds 'restoring login access' for clarity. It clearly distinguishes from sibling tools like disable_identities and delete_identities.
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 re-enabling previously disabled identities but does not explicitly state when to use it versus alternatives (e.g., disable, delete). No context on prerequisites or exclusions.
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?
Annotations indicate non-read-only, non-destructive, non-idempotent. The description adds that it updates dates and ETAs but does not disclose side effects, partial update behavior, or whether it returns updated consignments.
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: one for purpose, one for args. No unnecessary words, front-loaded with key action.
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?
No output schema, so return values are not described. Lacks details on date format, error handling, or prerequisites. However, for a simple update tool, the description is minimally adequate.
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 description explains that the 'updates' array contains objects with consignmentId and new despatch date/ETA, adding meaningful context beyond the schema's generic description. Schema coverage is 100%, but the description clarifies the structure.
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 'Updates' and the resource 'despatch dates and estimated time of arrival (ETA) for a set of consignments'. It distinguishes from sibling tools which are mostly for getting, creating, or deleting consignments or other entities.
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 mentions 'for a set of consignments' but provides no explicit guidance on when to use this tool versus alternatives like update_consignment_statuses or update_reprice_consignment. The title hints at manifest context, but the description does not clarify.
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 readOnlyHint=false and destructiveHint=false, so the agent knows it's a mutation. The description adds 'creates' which is consistent, but does not provide additional behavioral context such as permissions, side effects, or the structure of the consignment object.
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 extremely concise, consisting of two sentences and an Args line. It delivers the core information without any extraneous text.
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 annotations and schema coverage, the description lacks details about the consignment object's required fields, format of item IDs, or any constraints. A creation tool with a nested object parameter needs more guidance 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% for the single parameter, which has a generic description. The tool description adds context about 'previously saved company items' but does not elaborate on the structure or required fields of the consignment object, so it adds limited extra meaning.
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 it 'creates a consignment using previously saved company items (by item ID / SKU)', which is a specific verb and resource, and distinguishes it from siblings like machship_create_consignment (general) and machship_create_consignment_with_complex_items (for complex items).
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 indicates it is for using existing saved items, which implies when not to use (if no existing items), but it does not explicitly name alternatives or exclusion criteria.
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 indicate the tool is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds that it creates a draft, which is consistent. It does not disclose additional behavioral traits like permissions or limits.
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 relatively concise, with a short explanation followed by an Args section. Some redundancy exists with the schema, but it remains efficient.
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 lacks information about the return value (created consignment), error conditions, or prerequisites. Given no output schema, this is a gap for a creation 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?
Schema description coverage is 100% with the 'consignment' parameter described in the schema. The description repeats the listed fields (companyId, from/to address, items, references) without adding new 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 clearly states the tool creates a pending consignment, a draft/staging consignment that hasn't been rated or assigned to a carrier. It distinguishes from the sibling 'create_consignment' by emphasizing the pending/draft nature.
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 notes that pending consignments can be converted to full consignments after quoting, providing context on when to use this tool. However, it does not explicitly state alternatives or 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. Description adds 'This action is irreversible', which aligns. However, no additional behavioral traits like cascading effects or permission requirements are disclosed.
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 plus a parameter listing with no fluff. Every word is necessary and efficiently conveys the purpose and key constraint.
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 destructive tool with one parameter and annotations covering safety, the description is mostly complete. It could mention return value or error conditions but is sufficient for typical use.
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 schema already describes 'ids' thoroughly. Description repeats the parameter info without adding new meaning; baseline 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?
Description clearly states 'Delete the identities with the given IDs', which is a specific verb-resource combination. It distinguishes from sibling tools like create, get, disable, re-enable, and update identities.
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 notes the action is irreversible, implying caution, but does not explicitly guide when to use this tool versus alternatives like disable_identities (which might be reversible). No prerequisites or when-not-to-use advice is given.
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 indicate readOnlyHint=false, so mutation is clear. Description adds the key behavioral constraint 'Cannot edit manifested consignments.' No other behavioral details like side effects or permissions.
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 and an Args list with no extraneous information. Front-loaded with the core purpose and constraint.
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 mutation tool with a complex nested object parameter and no output schema, the description lacks guidance on the object structure beyond id, and does not mention the return value or any validation.
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 description repeats the schema's description of 'consignment' parameter. Adds no new semantic value beyond including the id.
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?
Clearly states the verb (Edits), resource (consignment), and condition (unmanifested). Distinguishes from siblings by noting it cannot edit manifested consignments.
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 says when to use (editing unmanifested consignments) and when not (manifested consignments). Does not name specific sibling tools but the constraint serves as guidance.
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 destructiveHint=false, ensuring safety. Description adds that the tool downloads a report with consignment details, but does not elaborate on additional behavioral traits.
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?
Description is concise with one clear sentence and an args block. No extraneous information, front-loads the purpose.
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 tool with one parameter and no output schema, the description covers the essential purpose and output contents. However, it could hint at the return format (e.g., binary download).
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 schema already describes the 'id' parameter as 'Attachment ID'. The description repeats this, adding no new semantic meaning beyond what the schema 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?
Description states 'Downloads a Proof of Delivery (POD) report' with specific verb and resource, and mentions 'attachment and consignment details,' distinguishing it from sibling tools like machship_get_attachment.
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?
Description implies usage context (getting a POD report) but provides no explicit guidance on when to use this tool versus alternatives like machship_get_attachment or machship_get_consignment.
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, destructiveHint=false, idempotentHint=true, so agent knows it's safe and non-mutating. Description adds that it returns entries with optional status filtering, but does not address pagination, result limits, or sorting. Given annotation coverage, this is adequate.
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?
Extremely concise: two sentences and a bullet list. No redundant words, front-loaded with the core action. Every element serves a purpose.
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 tool with 2 parameters, the description is nearly complete: it states purpose, identifies required and optional inputs, and covers filtering. Lacks mention of return structure (no output schema) but this is minor 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 100%, providing clear descriptions for both parameters. The description reiterates parameter names and types but adds no additional semantic context like allowed status values or format of carrierInvoiceId. Baseline 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?
Describes the tool as 'Gets carrier invoice line entries with optional status filtering.' The verb 'gets' and resource 'carrier invoice line entries' clearly define its action, and the name distinguishes it from the sibling 'machship_get_carrier_invoices' which retrieves invoices themselves.
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. Context implies use when needing line entries of a carrier invoice, but no mention of alternatives like seeking invoice summaries or other filtering capabilities. Agent would rely on schema and name cues.
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 readOnlyHint and idempotentHint, so the description adds limited behavioral context. It notes the return of a PDF but does not disclose any additional traits such as authentication requirements or file 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences and a short args list. No unnecessary words, and the main purpose is front-loaded. 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?
Given the simple tool with one parameter and no output schema, the description adequately states what the tool does and what it returns. It could mention the file format or that the response is a binary PDF, but the phrase 'commercial invoice PDF' is sufficient.
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 parameter consignmentId is documented in the schema with the same description. The description adds no extra meaning beyond the schema, which already has 100% coverage. 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 clearly states the tool returns the commercial invoice PDF for a consignment, using a specific verb and resource. This distinguishes it from other PDF retrieval tools like machship_get_dangerous_goods_pdf or machship_get_consignment_label_pdf.
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 mentions 'used for international shipments,' providing some context for when to use, but it does not explicitly differentiate from sibling PDF tools or state when not to use it. No alternatives are given.
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 readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, so the description's behavioral disclosure is not strictly required. The description adds no further behavioral details (e.g., authentication, rate limits, or what 'full details' entails), but is consistent 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 extremely concise: one sentence summarizing the function followed by a clear list of parameters. No unnecessary words, and the main purpose is front-loaded.
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 tool with three well-documented parameters and clear annotations, the description is nearly complete. The only minor gap is lack of output schema, but the phrase 'full details' adequately conveys the return value's scope.
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 itself fully documents each parameter. The description repeats parameter info without adding new meaning beyond the schema, earning baseline 3.
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 clearly states 'Returns full details for a single consignment by ID', which is a specific verb-resource pair that effectively distinguishes from sibling tools that retrieve multiple consignments or use other criteria.
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 guidance on when to use this tool versus alternatives like machship_get_consignments_by_ids or machship_get_consignment_by_pending_id. The usage is implied by the name and description, but there is no direct contrast or exclusion.
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, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the agent knows this is a safe, non-destructive operation. The description adds that it returns only metadata, not file contents, which is useful context. However, it does not elaborate on any side effects or limitations beyond what annotations 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 extremely concise: two sentences that front-load the core purpose and immediately clarify that it returns metadata only. No extraneous words or fluff.
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 metadata retrieval with one parameter and no output schema, the description covers the essential purpose and parameter. It could optionally list metadata fields (e.g., filenames, sizes) but is sufficient given annotations and tool 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?
The input schema provides a 100% covered parameter 'consignmentId' with description 'Consignment ID.' The tool description repeats this information without adding new meaning or constraints. Baseline is 3 for high 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 'Returns attachment metadata (not file contents) for a consignment,' which specifies the verb (returns), resource (attachment metadata), and scope (for a consignment). It distinguishes from sibling tools like machship_get_attachment (which returns file contents) and machship_upload_attachments.
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 hints at usage by noting it returns metadata not file contents, implying that for file contents one should use another tool. However, it does not explicitly state when to use this tool versus alternatives like machship_get_attachments_by_consignment_ids or machship_get_attachment, leaving room for ambiguity.
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 clear. The description adds the batch size limit (max 100) but does not disclose details about return format, error handling, or authentication requirements. The statement 'Returns details' is vague.
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 extremely concise, consisting of two short sentences with no fluff. The key information (purpose and parameter) is front-loaded. Every word contributes value.
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 simplicity (one parameter, no output schema, no nested objects) and the strong annotations, the description provides sufficient context for a basic read operation. It could mention that the output matches individual consignment details, but the current level is adequate for agent understanding.
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 has 100% coverage (the 'ids' parameter is fully described in the schema as an array of integers with min/max). The description merely restates the schema comment, adding no new semantic information about the parameter beyond what is already in 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 states the tool returns details for multiple consignments by their IDs, distinguishing it from sibling tools like 'get_consignment' (single) and other batch retrieval tools by specifying the use of consignment IDs directly. The max limit of 100 further clarifies scope.
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 usage when a list of consignment IDs is available, but it lacks explicit guidance on when to use this versus alternatives like 'get_consignments_by_carrier_id' or 'search_consignments'. No when-not-to-use 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by specifying the output type (statuses) and optional date filtering. However, it does not disclose error behavior for invalid IDs, rate limits, or what 'statuses' entails beyond tracking/delivery.
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 extremely concise: one sentence for purpose followed by two parameter descriptions. No wasted words, and the essential information is front-loaded. Every sentence serves a clear purpose.
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 simple 2-parameter tool with no output schema, the description adequately covers the inputs and basic behavior. It doesn't explain the return format (e.g., array of status objects), but for a read-only tool with strong annotations, it is sufficiently 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 coverage is 100%, the descriptions in the description duplicate the schema descriptions (e.g., 'Consignment IDs', 'Only return statuses since this UTC datetime (ISO 8601)'). No additional semantics are provided beyond what the schema already conveys.
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 'returns tracking/delivery statuses for a batch of consignments', using a specific verb and resource. It distinguishes itself from sibling tools like 'get_consignment' (returns single consignment details) and 'get_consignments_by_ids' (returns consignment objects) by focusing on statuses and batch processing.
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 batch use via 'batch of consignments' and the 'ids' parameter, but it does not explicitly state when to use this tool versus alternatives like 'get_consignment' or 'update_consignment_statuses'. No exclusions or when-not-to-use 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`, `destructiveHint=false`, and `idempotentHint=true`, so the agent knows this is safe and idempotent. The description adds minimal behavioral context by explaining that it returns all custom schemas and what they are, but does not disclose anything beyond what annotations imply (e.g., no mention of pagination or output format). With annotations handling most of the burden, a score of 3 is appropriate.
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, front-loading the primary purpose (returns all custom schemas) and then clarifying the domain (what custom schemas are). Every sentence earns its place with no redundant or extraneous 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 tool has no parameters, no output schema, and the annotations are rich, the description adequately conveys the tool's role. It defines the output concept (all custom schemas) and the entity type. Minor improvement could mention that no filtering or pagination is available, but the description is sufficient for an agent to understand when to select this tool.
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 schema coverage is 100%. The description adds meaning by explaining what a custom schema is, which helps the agent understand the return value. Since there are no parameters to document, a baseline of 4 is justified.
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 it returns all custom schemas, defines what custom schemas are, and the name `get_custom_schemas` (plural) distinguishes it from the singular `get_custom_schema` sibling. This gives the agent a precise understanding of the tool's function.
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 on when to use this tool versus alternatives like `get_custom_schema` (singular) or other get-* tools. The description assumes the agent knows to choose this when needing all schemas, but no explicit context or exclusion criteria are given.
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 read-only, non-destructive, idempotent, open-world. Description adds value by specifying it returns detailed dimensions/packaging data, which is beyond structured fields.
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 verb and resource, no wasted words. Perfectly concise.
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 one parameter, no output schema, and comprehensive annotations, the description is sufficient. Could mention return format or error cases for higher score, but not necessary for basic get-by-ID 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?
Single parameter 'id' with schema description 'Item ID'. Description mentions 'number' but adds no substantial meaning beyond schema; schema coverage is 100%, so baseline 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?
Description clearly states it returns a single complex item with detailed dimensions/packaging data by ID, distinguishing it from siblings like get_item or get_items_complex.
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 on when to use this tool vs alternatives; lacks context on prerequisites or exclusions.
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, destructiveHint=false, and idempotentHint=true, so the description's additional mention of returning a PDF adds minimal behavioral context. No contradictions 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?
Two short sentences that front-load the purpose and efficiently list parameters. No extraneous 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 no output schema, the description could clarify what the PDF contains (e.g., label dimensions). However, it is adequate for a simple retrieval tool with good annotations.
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 coverage is 100%, so baseline is 3. The description adds value by stating the default for printA4 ('default: label-size') and specifying that consignmentId is a number, enhancing parameter understanding 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 states the tool returns 'item/package labels for a consignment as a PDF,' specifying the verb and resource. It distinguishes from siblings like get_consignment_label_pdf and get_item_labels_zip by focusing on item labels in PDF format.
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?
Description provides no guidance on when to use this tool versus alternatives such as get_consignment_label_pdf or get_item_labels_zip. It lacks any context about prerequisites or exclusions.
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?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds no behavioral traits beyond what annotations provide (e.g., pagination behavior, empty result handling). It merely restates parameters.
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 concise: one sentence for purpose followed by a clean parameter list. Every sentence is necessary, and the key information is front-loaded. No fluff.
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 has 4 optional parameters and no output schema, the description adequately states what the tool returns (linked organisations). It could mention the return format (array of objects) but is largely complete for the complexity level.
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 each parameter's meaning: startIndex for pagination start, retrieveSize for count, sort field, searchText for name filtering. This adds value over the schema's type and constraint information.
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 title and description clearly state the tool returns all organisations linked TO the current organisation (customers, subsidiaries). This verb+resource combination distinguishes it from siblings like machship_get_linked_from_organisations (reverse direction) and machship_get_organisation_links (general).
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 usage context by specifying direction ('linked TO'), but it does not explicitly state when to use this tool versus alternatives like get_linked_from_organisations or get_organisation_links. 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 indicate read-only, non-destructive, idempotent behavior. Description adds the specific output type (PDF), no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise, front-loaded, and efficient. Every word is necessary.
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 tool with one parameter and rich annotations, the description adequately conveys purpose and output. Slight lack of explicit return format but tolerable.
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 description repeats the parameter info without adding new semantics 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 states it returns a manifest document as a PDF by manifest ID, distinguishing it from sibling tools like get_manifest_label_pdf_by_consignment.
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 on when to use this tool vs alternatives like get_consignment_label_pdf or get_manifest_label_pdf_by_consignment. Exclusions or context are missing.
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?
Description adds that the consignment must be in an unmanifested state and the output format is for editing, which is useful. Annotations already declare readOnlyHint true, so the safety profile is clear. No contradictions, and description provides moderate additional context beyond 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?
Description is extremely concise: two sentences with no unnecessary words. First sentence states purpose, second lists the argument. Front-loaded and efficient.
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 get operation with one parameter and full annotation coverage (readOnly, idempotent, etc.), the description is complete. It explains the specific purpose (for edit) and the required state (unmanifested). No output schema, but the description adequately signals what to expect.
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%, so the schema already documents the 'id' parameter with the constraint 'must be unmanifested'. Description repeats this constraint and adds no new semantic detail. Baseline 3 applies as schema does the heavy lifting.
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 clearly specifies 'Get an unmanifested consignment' with the purpose 'required to perform an update via the editUnmanifestedConsignment endpoint'. It distinguishes this tool from other consignment getters (e.g., get_consignment, get_unmanifested_consignments) by focusing on edit-ready format.
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?
Description implies usage context (for editing unmanifested consignments) but does not explicitly state when to use this tool versus alternatives like get_consignment or get_unmanifested_consignments. No sibling differentiation or exclusions 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 destructiveHint=false, indicating a safe preview operation. The description adds 'preview before manifesting', which is consistent. No contradictions, but no further behavioral details beyond 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 sentences plus an argument list, front-loaded with the core purpose. Every sentence is meaningful and concise, with no extraneous 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 tool has a single parameter, no output schema, and annotations cover the safety profile, the description is sufficiently complete for basic understanding. It might lack detail on edge cases (e.g., already grouped consignments) but is adequate.
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% for the only parameter 'consignmentIds'. The description merely repeats the argument definition, adding no new meaning beyond what the schema already provides. Baseline 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 clearly states the tool groups specific consignments into manifest groups as a preview. It distinguishes from siblings like 'machship_group_all_for_manifest' (all consignments) and 'machship_manifest_consignments' (actual manifest) by mentioning 'preview before manifesting' and 'specific 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 implies usage for previewing grouping, but does not explicitly state when to use this vs. alternatives like group_all_for_manifest or group_and_perform_consolidation. No exclusions or context about prerequisites are given.
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, destructiveHint false, and idempotentHint true. The description adds that it returns a zip of PDFs, which provides useful but limited behavioral context. No additional details on authentication, rate limits, or side effects are given beyond what annotations cover.
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 concise, with two sentences and a clear argument list. It front-loads the core action and provides all necessary information without superfluous 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 read-only, idempotent tool with simple parameters and thorough annotations, the description sufficiently covers the input constraints and return format. It could elaborate on the contents of the zip file, but overall it is complete enough for agent selection.
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 both parameters. The description reiterates the parameter names and basic purpose without adding further semantic detail like expected formats or edge cases.
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 returns item labels as a zip for up to 40 consignments, using a specific verb and resource. It distinguishes the POST variant from a likely GET counterpart, aligning well with the tool's purpose.
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 gives context for when to use this POST variant (body payload preferred) and includes a maximum limit of 40 consignments. However, it does not explicitly state when not to use this tool or compare with siblings like 'get_item_labels_zip', leaving room for ambiguity.
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 disclose readOnlyHint, destructiveHint, and idempotentHint, which are consistent with a 'remove' operation. The description adds the basic behavioral trait of removing access. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise paragraph with two sentences, front-loading the purpose and then detailing parameters with no 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?
Given the simple input schema and no output schema, the description adequately explains the tool's purpose and input structure. It is sufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each field. The description lists the args inline but adds no additional meaning beyond the schema. Baseline 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 uses a specific verb 'Remove' and resource 'company access from identities', clearly distinguishing it from the sibling tool 'machship_link_identities_to_companies' which performs the opposite operation.
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 usage for revoking company access from identities, but does not provide explicit when-to-use or alternatives. However, the action is straightforward and the purpose is clear.
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 indicate it is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds that it uses a public key, but does not disclose side effects, return behavior, or permission requirements. Adequate but not comprehensive.
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 very concise: two sentences and an args list. The main action is front-loaded, and every sentence adds value without repetition or fluff.
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?
With one parameter, no output schema, and siblings for link management, the description covers the core action but lacks details on return values or expected outcomes. It is minimally viable but could provide more context.
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 input schema describes the 'request' parameter as a link request with publicKey. The description adds 'optional configuration', which is not in the schema description, providing additional semantic value. Schema coverage is 100%.
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 'Links' and the resource 'another organisation into yours' using a specific method (public key). It distinguishes from related tools like remove_organisation_link and get_organisation_links.
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 usage when you have the partner's public key but does not explicitly state when to use this tool versus alternatives (e.g., remove or get links). No exclusions or prerequisites 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 declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds that the tool returns 'active (in-transit)' consignments, which aligns with annotations and provides additional context. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one sentence stating the tool's purpose followed by a bulleted list of parameters. No extraneous information, front-loaded with the main action.
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 read-only tool with 5 parameters and no output schema, the description covers input parameters but does not describe the return format or provide details about response structure. Given the richness of annotations, this is adequate but leaves some gaps.
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 describes each parameter. The description's 'Args' list essentially repeats the same information without adding significant meaning beyond what is in 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 states the tool returns all active (in-transit) consignments for a company, using a specific verb and resource. It distinguishes this from siblings like 'get_all_consignments' or 'get_completed_consignments' by specifying the 'active' 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 description implies usage for retrieving active consignments but does not provide explicit guidance on when to use this tool versus alternatives (e.g., 'get_all_consignments' for all statuses, 'get_completed_consignments' for completed ones). No exclusion criteria or prerequisites 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 indicate read-only, idempotent, safe behavior. The description adds that the tool retrieves roles 'available to assign', which provides context but does not disclose additional behavioral traits like error handling or scope. Given the annotations, the description is adequate but not enhanced.
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 extremely concise with two sentences: one for the tool's purpose and one for the argument list. Every sentence is necessary and front-loaded with the core action.
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 tool's simplicity (one required parameter, no output schema, rich annotations), the description provides sufficient context: what the tool does, what it takes, and the scope. No additional information is necessary.
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 provides 100% coverage with a description 'Company ID' for the sole parameter companyId. The tool description repeats this same information without adding further meaning, so it does not add value 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 states the verb 'Get' and resource 'roles' with the specific context of roles available to assign to users of a company. It is unambiguous and distinct from sibling tools, which focus on other resources like consignments, companies, etc.
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 (to retrieve assignable roles for a company) but does not explicitly state when not to use it or provide alternatives. Since there are no sibling tools for roles, the usage context is implied, but explicit guidance is missing.
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, destructiveHint=false, idempotentHint=true. The description adds 'without downloading', which reinforces non-destructive behavior. However, it lacks details on authentication requirements, rate limits, or potential side effects beyond what annotations cover.
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 long, front-loaded with the purpose, and includes a clear argument list. Every sentence earns its place without redundancy or unnecessary detail.
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 metadata retrieval tool with no output schema, the description adequately lists the returned fields (name, size, URL). Combined with the informative annotations and simple parameter, no additional information is necessary for an agent to understand the tool's 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 input schema describes consignmentId as 'Consignment ID' with type integer. The description restates the same information in Args without adding extra context (e.g., format, source, or validation rules). Since schema coverage is 100%, the description adds no additional meaning.
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 returns file metadata (name, size, URL) for the consignment label PDF without downloading it. This specific verb+resource combination effectively distinguishes it from sibling tools like 'machship_get_consignment_label_pdf'.
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 usage for getting metadata instead of downloading, but does not explicitly state when to use this tool versus alternatives. No when-not-to-use or alternative names are provided, leaving the agent to infer context from the tool name alone.
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 readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds that it limits results to a max of 10, providing extra behavioral context. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using a single sentence for the purpose and a bullet for the argument. No redundant 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 simplicity of the tool (one parameter, no output schema), the description is largely complete. It covers the key constraint (max 10) and the nature of the IDs. It could mention what happens if IDs are not found, but this is a minor gap.
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 description defines the parameter as an array of carrier consignment IDs with a max of 10, clarifying that these are 'carrier's own consignment/tracking ID'. This adds context beyond the schema's description, which only says 'Carrier consignment IDs (max 10)'.
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 states it finds consignments by the carrier's own consignment/tracking ID. It specifies the resource and the lookup key, but does not explicitly differentiate from sibling tools like get_consignments_by_ids or search_consignments.
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 mentions a max limit of 10 per request, which is a constraint, but does not provide explicit guidance on when to use this tool versus alternatives (e.g., when you have a carrier ID vs. internal ID). Usage is implied by the tool name.
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 read-only, non-destructive, idempotent behavior. The description adds that it returns metadata without downloading, which is valuable context beyond annotations. However, it does not specify what metadata is returned (e.g., file size, name) or error conditions.
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 wasted words. Front-loaded with the core action (returns metadata) and clarifies 'not downloading'. Excellent conciseness.
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's simplicity (one param, no output schema, good annotations), the description covers the basic function. However, it lacks details on return format, required permissions, or edge cases like invalid manifestId. Could be more 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 covers the single parameter with a description. The description restates the parameter name and type but adds no new meaning. Since schema description coverage is 100%, 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 clearly states the tool returns file metadata for a manifest PDF without downloading it. It uses a specific verb ('returns') and resource ('manifest PDF'), distinguishing it from siblings like machship_get_manifest_label_pdf or machship_download_manifest.
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. The description implies its use for metadata retrieval without downloading, but does not mention alternatives or conditions.
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=true, destructiveHint=false, idempotentHint=true. Description adds no extra behavioral traits beyond what annotations and schema cover. It is consistent but not additive.
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-sentence structure: first sentence states purpose, second is a clear bullet list of parameters. No wasted words, front-loaded with key info.
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 5 parameters and no output schema, the description explains the tool's return focus (unmanifested consignments) but omits details like response format, pagination behavior, or error conditions. Adequate but not fully comprehensive.
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% with each parameter described. The description's parameter list merely repeats schema descriptions (e.g., 'Company ID'), adding no new meaning or usage nuance.
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 clearly states the tool 'Returns consignments that have been created but not yet manifested', using a specific verb (returns) and resource (unmanifested consignments). It distinguishes from numerous sibling get_consignments tools that target different states (active, completed, all, etc.).
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?
Description defines the use case (unmanifested consignments) implicitly but does not explicitly state when not to use it or suggest alternatives. The context is clear enough for an agent to decide, though missing explicit exclusions.
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 (readOnlyHint=false, destructiveHint=false, idempotentHint=false) provide some safety context. The description adds that it operates on an 'existing manifest', but lacks details on side effects, cancellation of old pickup, or required permissions. 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?
Two sentences with an Args section, front-loaded with purpose. Every word is necessary; no redundancy or wasted text.
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 tool with one nested parameter and no output schema, the description covers the purpose and parameter essentials but omits details on return value, success/failure indicators, or postconditions. Adequate for a minimal viable definition.
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 coverage is 100% for the single parameter, but the description adds value by explicitly specifying expected fields within the object: 'manifestId and new pickup datetime'. This clarifies the structure beyond the generic schema 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 states the action 'Rebooks' and the resource 'carrier pickup for an existing manifest' with specific examples like missed pickup or changed schedule. This distinguishes it from sibling tools such as 'machship_get_manifests' or 'machship_manifest_consignments'.
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 usage with examples like 'missed pickup or changed schedule', but does not explicitly state when not to use it or compare to alternatives among the many sibling tools. No guidance on prerequisites or 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 declare destructiveHint=true; description adds 'irreversible', providing extra behavioral context beyond 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 short sentences with clear purpose; no unnecessary words.
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?
Adequate for a simple destructive action, but missing description of return value or response (no 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?
Schema coverage 100%; description adds minor detail ('organisationLinkId') but largely repeats schema info. 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 specific verb 'Removes' and resource 'existing link between two organisations', clearly differentiating from sibling 'add_organisation_link'.
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?
Implies usage for removing organisation links but does not explicitly state when to use vs. alternatives or any prerequisites.
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 destructiveHint=true. The description adds the unmanifested constraint, which is valuable beyond annotations. However, it doesn't disclose other behavioral details like reversibility, cascading effects, or authentication requirements. With annotations providing the base safety profile, the addition is useful but not comprehensive.
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 plus an args list; no wasted words. Purpose is front-loaded. Every sentence contributes essential 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 destructive nature (annotations) and full schema coverage, the description covers the main behavioral constraint (unmanifested). It does not describe return values or error handling, but with no output schema, this is acceptable. Adequate for an agent to use safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'ids'. The description's 'Args' section merely restates schema info without adding new semantic meaning. Baseline 3 applies as the schema already documents the parameter 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?
Description clearly states 'Deletes multiple unmanifested consignments' using specific verb (delete) and resource (consignments) with a key constraint (unmanifested). It distinguishes from sibling tools like machship_delete_item or machship_delete_pending_consignments.
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 states 'Cannot delete manifested consignments', providing a clear when-not-to-use condition. While it doesn't name alternative tools, the constraint is clear enough for an agent to avoid misuse.
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 (readOnlyHint=true, idempotentHint=true) indicate a safe read operation. The description adds behavioral insight by noting that the consignment details are retrieved 'if it exists', implying possible null result. This adds value beyond 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 short and front-loaded with the purpose. However, the Args section is redundant given the schema, which slightly reduces conciseness. Still efficient overall.
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 tool's simplicity (one parameter, no output schema), the description covers the essential information: what it does, the condition (if exists), and the parameter. No further details are needed for a complete understanding.
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% (the only parameter 'id' is fully described in the schema). The description's Args section merely repeats the schema information without adding new meaning, so no additional value for semantics.
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 'Get consignment details' using a specific resource (pending consignment ID that has been transformed into a consignment). It distinguishes from sibling tools like machship_get_consignment (which uses a consignment ID) and machship_get_pending_consignment (which gets pending consignment).
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 that the tool is for getting consignment details from a pending consignment ID that has been linked, but it does not explicitly state when to use this tool over alternatives (e.g., machship_get_consignment_by_ids or machship_get_pending_consignment). Usage context is implied but not explicit.
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 readOnly, destructive, idempotent, and openWorld hints. The description adds that it returns metadata, which is appropriate, but does not detail the metadata fields, leaving partial transparency for a tool with 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first sentence states purpose with key differentiation, second lists the parameter. No redundancy, front-loaded, and efficient.
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 one-parameter read-only tool, the description is mostly complete. Minor gap: does not specify what 'file metadata' includes, which could be clarified given no 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?
Schema coverage is 100% and the description restates the parameter without adding new meaning; baseline score 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 clearly states the verb 'Returns', the resource 'file metadata for the dangerous goods declaration PDF', and the key qualifier 'without downloading it', effectively distinguishing it from sibling tool machship_get_dangerous_goods_pdf.
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 'without downloading it' implies when to use this tool versus the download variant, but does not explicitly specify alternatives or conditions, leaving some room for ambiguity.
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, destructiveHint false, idempotentHint, and openWorldHint, indicating a safe read operation. The description adds no additional behavioral traits (e.g., pagination, rate limits, response structure) beyond what annotations and schema provide. With annotations covering the safety profile, a score of 3 is appropriate.
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 concise: three sentences plus a structured Args list. The first sentence states purpose directly. Every sentence adds value. The format is front-loaded and easy to scan.
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 has 3 parameters and no output schema, the description adequately covers the purpose, required access, and parameter details. It could optionally mention the return type or pagination, but the information provided is sufficient for an agent 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?
Schema description coverage is 100% (all 3 parameters are described in the schema). The description repeats the parameter names and types, adding only minor clarity (e.g., labeling 'onlyUnlinkedIdentities' as optional). This does not significantly enhance understanding beyond the schema, so baseline 3 is correct.
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 retrieves all identities owned by an organisation, including details on linked companies. This specific verb-resource-scope combination distinguishes it from sibling tools like machship_get_identity (single identity) and machship_create_identities.
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 mentions a prerequisite: 'Requires administrator access to the organisation.' It implicitly indicates use for listing identities, but does not explicitly state when to use this tool over alternatives like machship_get_identity or machship_get_identity_providers_for_organisation. The context is clear but lacks explicit 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=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds valuable behavioral details beyond annotations, such as pagination with startIndex and retrieveSize parameters and a maximum of 200 items per request.
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 short, front-loaded with the main purpose, and uses a clear Args structure. Every sentence provides essential information with no 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 straightforward list tool, the description covers the main points: pagination, max size, and required parameters. No output schema is present, but the return value is implied to be a list of items. The description is complete enough 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 coverage is 100%, with all three parameters having descriptions in the schema. The description repeats parameter info in a structured format, adding defaults and constraints but not providing novel meaning beyond what the schema already offers. Baseline 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 clearly states the tool returns a paginated list of saved items for a company, specifying the verb (returns), resource (list of saved items), and constraints (max 200 per request). This distinguishes it from sibling tools that get a single item or filter by SKU.
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 that this tool is for retrieving a list of items for a company, but it does not explicitly state when to use it over alternatives like machship_get_item, machship_get_items_by_skus, or others. No when-not or alternative 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. Description adds that it returns exact matches and supports multiple lookups, which is consistent but not significantly expanding on 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?
Description is extremely concise: two sentences for purpose and batching, plus a minimal Args list. No wasted words, front-loaded with key 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 simple lookup nature, full schema coverage, and comprehensive annotations, the description is adequate. It covers exact matching, batch capability, and parameter structure. No output schema, but the return type is implied.
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 description's parameter documentation ('Array of suburb/postcode pairs to look up exactly') mirrors the schema. It adds no new 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 tool name and title clearly indicate exact match location lookup. Description specifies 'exactly match provided suburb/postcode combinations', distinguishing it from fuzzy search siblings like machship_search_locations.
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?
Description states supports multiple lookups per call, implying batch usage. It does not explicitly contrast with alternatives like machship_search_locations or machship_get_locations_with_options, but the name and description make the exact-match use case obvious.
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 destructiveHint=false, so the description's addition of 'without downloading' provides some context but is not critical. The description does not disclose other behavioral aspects like return format or pagination, which, given no output schema, would be valuable. Still, annotations carry most of the transparency burden here.
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 extremely concise: three lines with no unnecessary words. It front-loads the purpose and then lists the parameter. Every sentence is essential and earned 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 the tool's simplicity (one param, no output schema), the description is mostly adequate. However, it omits what specific metadata fields are returned (e.g., file name, size, type). For a file info tool, this could help the agent decide if it's sufficient. Still, the core purpose is clear and complete for basic use.
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% with description 'Consignment ID' for the only parameter. The description repeats this exactly without adding new meaning (e.g., format, source, or constraints). With high schema coverage, baseline is 3, and this description meets it without enhancement.
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 'Returns' and the resource 'file metadata for the MO41 document PDF', distinguishing it from sibling tools like machship_get_mo41_document_pdf which presumably downloads the file. The title also aligns well.
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 hints at usage by saying 'without downloading it', implying that if the agent needs the actual file, it should use another tool. However, it does not explicitly name the alternative tool or provide when-not-to-use conditions. Given the large set of siblings, a more explicit reference would be better.
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, destructiveHint, idempotentHint, openWorldHint, setting a high baseline. The description adds value by specifying that leaving id blank defaults to the current authenticated org, and that it returns 'all links', which clarifies the scope of the 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?
The description is extremely concise with two sentences: the first defines the purpose, the second explains the parameter. Every sentence earns its place; no unnecessary 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 operation with one optional parameter and no output schema, the description covers the core functionality and parameter usage. It could briefly mention the return type (e.g., list of link objects), but the current level is largely adequate.
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 description text for the parameter ('Organisation ID (optional, defaults to current org)') is nearly identical to the schema description. No additional semantic 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 the tool returns all links (partnerships/integrations) for an organisation, using a specific verb ('Returns') and resource. It distinguishes from siblings like machship_get_linked_from_organisations by focusing on all links for an organisation, and clarifies the optional id parameter.
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 (to retrieve links) and explains the id parameter, but does not explicitly contrast with other link-related tools or state when not to use it. No direct guidance on alternatives.
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?
Description warns 'This is irreversible', adding context beyond annotations that already indicate destructiveHint=true. No contradictions; description aligns with and slightly extends 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 short, clear sentences. First sentence states action and parameter; second warns about irreversibility. No unnecessary 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 simple delete tool with one required parameter and no output schema, the description provides all necessary information: what it does, the parameter needed, and a critical warning about irreversibility.
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?
Only one parameter (id) with schema description 'DotNet class ID'. The description restates this but adds no further meaning. Schema coverage is 100%, so description adds minimal value beyond 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?
Clearly states the verb 'Deletes' and resource 'custom schema by its DotNet class ID'. Distinguishes from sibling tools like machship_create_custom_schema and machship_get_custom_schema.
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 guidance on when to use vs alternatives or prerequisites. The description only explains what the tool does, not when it should be chosen over other delete tools.
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 a safe read operation (readOnlyHint, destructiveHint false, idempotent). The description adds valuable behavioral context: the zip return format and the bulk nature (up to 40 IDs). This goes beyond what annotations 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 extremely concise with two sentences, front-loading the key action and output format. Every word is informative with no fluff.
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 tool with no output schema and thorough annotations, the description provides sufficient context: what it does (download attachments), scope (up to 40 consignments), format (zip). No additional information is needed.
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 fully covers the parameter, and the description only repeats the same information (array of IDs, max 40). No additional semantic meaning is added 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 states it downloads attachments for multiple consignments (up to 40) and returns a zip. This distinguishes it from sibling tools like machship_get_attachment (single) and machship_get_consignment_attachments (per consignment).
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 usage for bulk attachment downloads but does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it. The parameter limit is noted, but no direct comparison with 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?
Annotations already indicate read-only, non-destructive, idempotent, and open-world behaviors. The description adds a critical behavioral constraint ('Max 10 per request') that is not captured by annotations, increasing transparency. No contradictions found.
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 extremely concise: two lines for the main description and one line for the argument. Every sentence adds value, and the key information is front-loaded. No wasted 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 simple tool with one parameter and no output schema, the description is complete. It covers the purpose, constraint, and parameter format. The existing annotations and schema provide sufficient context, and the description fills the gap by adding the request limit.
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 covers 100% of parameters, and the description essentially restates the schema ('references (string[]): Array of Reference 1 values (max 10)'). No additional semantics beyond the schema are provided, so the baseline score 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 clearly states the action ('Finds'), resource ('consignments by their Reference 1 field'), and a key constraint ('Max 10 per request'). It effectively distinguishes this tool from siblings like get_consignments_by_ids and get_consignments_by_reference2.
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 usage when you have Reference 1 values but does not explicitly state when to use this tool over alternatives or provide exclusions. Among many similar fetch tools, no guidance is given on differentiation.
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 destructiveHint=false, indicating safe read operation. Description adds functional context—returning public key for inter-org link setup—which is beyond what annotations provide. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is two sentences: first states the result, second lists the parameter. Extremely concise and front-loaded with essential information.
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 tool with full annotations, one optional parameter, and no output schema, the description fully covers the tool's purpose and parameter role. Complete for effective use.
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?
Only one optional parameter 'id' with schema description 'Organisation ID (optional)'. Description text repeats this same information without adding new meaning. Since schema coverage is 100%, baseline is 3.
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?
Title and description clearly state the tool returns the public key for an organisation, used for inter-organisation links. This distinguishes it from sibling tools like machship_get_organisation_by_public_key which takes a public key as input.
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?
Description mentions the tool is used to set up inter-organisation links, implying context. However, it does not explicitly state when to use this tool versus alternatives (e.g., get_organisation_by_public_key, get_organisation_links), nor does it provide 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 readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the 'Max 10 per request' limitation, which is valuable behavioral context beyond the annotations. It does not contradict any 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 extremely concise: two short sentences and a clear parameter list. Every word is necessary. No fluff or repetition.
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's simplicity (single parameter, no output schema), the description covers the core intent. However, it does not describe the return format or any pagination behavior, which would be helpful. Still, it is adequate for a straightforward lookup tool with rich annotations.
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% (the single parameter 'references' is fully described in the schema). The description essentially repeats the schema's description ('Reference 1 values (max 10)'), adding no additional meaning. Baseline 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 uses the specific verb 'Finds' and identifies the resource 'pending consignments by Reference 1 field,' clearly distinguishing it from siblings like machship_get_consignments_by_reference1 (which retrieves non-pending consignments) and machship_get_pending_consignments_by_reference2.
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 specifies the maximum input size ('Max 10 per request'), which provides a clear usage constraint. However, it does not explicitly state when to use this tool versus alternatives (e.g., when to use machship_get_pending_consignments_by_ids), 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds behavioral context by specifying that administrator access is required, which goes beyond annotations. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences and an argument list. It is front-loaded with the primary purpose, then provides usage context and parameter details. No irrelevant information, every sentence serves a purpose.
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 operation with one parameter and no output schema, the description adequately covers purpose, required access level, and parameter meaning. It does not need to explain return values since it states 'Get the public keys'. Annotations provide additional safety context. The description is complete for this tool's 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 coverage is 100% as the parameter 'ids' is described in both schema and description. The description adds minimal additional meaning by paraphrasing the schema's description ('Identity IDs' becomes 'Array of identity IDs to retrieve public keys for'). With high schema coverage, baseline 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 clearly states the tool retrieves public keys for given identities, using a specific verb 'Get' and a resource 'public keys'. It distinguishes from sibling tools like machship_get_identity and machship_get_identities by focusing on public keys and their intended use for granting access via linked organisations.
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 mentions 'Requires administrator access' as a prerequisite but does not explicitly state when to use or not use this tool versus alternatives. It implies usage when public keys are needed for granting access, but lacks explicit guidance on conditions or 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 cover readOnly, destructive, idempotent, and openWorld hints. The description adds a useful behavioral constraint (max 2000 results), but does not describe return format or pagination details beyond that.
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 plus a clear bullet list, front-loaded with core purpose, no redundancy or fluff.
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 complete for a read-only query with annotated safety traits, but lacks details on the return structure (e.g., list of consignment objects) since no output schema is provided.
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 75%. The description repeats schema descriptions for 3 params and adds a brief description for includeChildCompanies (missing in schema). No additional semantic detail beyond labels.
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 'returns' and the resource 'completed (delivered) consignments' with a date range and max 2000 results, distinguishing it from siblings like get_active_consignments or get_all_consignments.
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 implies usage for retrieving delivered consignments within a date range, and the max results hint at pagination considerations, but lacks explicit when-to-use vs alternatives like get_active_consignments.
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 a safe read operation (readOnlyHint=true). The description adds that the output is specially formatted for cloning, which provides behavioral context beyond the annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus an args list, front-loaded with the core purpose. Every sentence adds value 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?
No output schema, but the description clarifies the output format (passable to createConsignmentWithComplexItems). Given the simple one-parameter tool and annotations, this is adequately complete for an agent.
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%, so baseline is 3. The description repeats the schema's parameter description ('Consignment ID') with minor wording change, adding no significant new meaning.
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?
Clearly states the verb 'Get', the resource 'consignment', and the specific purpose 'in a format that can be passed directly to the createConsignmentWithComplexItems endpoint to create a copy', distinguishing it from sibling get-consignment 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?
Explicitly describes when to use this tool (to create a copy via the createConsignmentWithComplexItems endpoint). Does not explicitly mention when not to use or alternatives, but the use case 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 a behavioral trait beyond annotations: the maximum batch size of 100 consignments. Annotations already cover safety (readOnly=true, etc.), so the description provides complementary 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 extremely concise, with two sentences and a bulleted arg list. No unnecessary words, and all information is front-loaded.
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 batch retrieval tool with no output schema, the description is mostly complete: it explains the purpose, the parameter, and a key constraint. However, it does not describe the return format (e.g., array of consignments).
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 description repeats the schema information for the single parameter 'ids' (type, min/max). Since schema coverage is 100%, the description adds minimal new meaning.
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 'Get', the resource 'consignment details', and the lookup method 'using Pending Consignment IDs'. It distinguishes from siblings by specifying 'multiple consignments' and 'batch', differentiating it from the single-consignment sibling tool.
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 implies usage for batch retrieval by pending IDs and sets a clear context (max 100 consignments), but does not explicitly mention when not to use it or provide alternatives.
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, destructiveHint=false, idempotentHint=true. The description adds value by clarifying the specific meaning of 'linked from' (suppliers/partners), and no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence for purpose and a parameter list. No superfluous 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 no output schema, the description explains the return value scope (organisations that linked into this org) and all parameters. It does not mention pagination details or return format, but for a simple list tool with good annotations, it is nearly 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 coverage is 0% (no descriptions in schema). The description's docstring provides brief descriptions for each parameter (e.g., 'Pagination start index'), compensating minimally. It adds meaning but lacks details like allowed sort 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?
Description uses specific verb 'Returns all organisations that have linked INTO this organisation (suppliers, partners).' This clearly identifies the resource (linked-from organisations) and distinguishes from sibling tool machship_get_linked_to_organisations.
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 implicitly differentiates from the sibling by specifying direction of links ('linked INTO'), providing clear context for when to use this tool. However, it does not explicitly state when not to use it or mention alternatives.
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 read-only, non-destructive, idempotent, and open-world behavior. The description adds the max 10 limit and that it returns details, providing useful context 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 extremely concise and front-loaded, with a single sentence for purpose and a clear parameter list. Every sentence is necessary, and no redundancy exists.
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 batch retrieval tool with full schema coverage and clear annotations, the description is adequate. It does not specify return format, but given the simplicity of the tool and the presence of similar sibling tools, it is sufficiently 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 coverage is 100%, and the description mostly restates the parameter info from the schema. It does not add new semantic meaning beyond what the schema provides, aligning with the baseline score for high 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 it returns details for multiple pending consignments by IDs, with a batch limit of 10. It distinguishes itself from siblings like get_pending_consignment (singular) and other retrieval methods by reference fields.
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 implies usage for batch retrieval by IDs, but does not explicitly state when to use versus alternatives like reference-based lookups. Context signals provide clear sibling differentiation, though no exclusions are mentioned.
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?
Adds useful context beyond annotations: specifies that existing links are unaffected. Annotations already indicate not read-only and not destructive; this description reinforces safety and adds a specific behavioral guarantee.
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?
Extremely concise: two sentences and a parameter list. All information is front-loaded and no unnecessary words. Every sentence adds value.
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?
Sufficient for a simple tool with one optional parameter and no output schema. Covers the main action, parameter, and key behavioral note. Minor gap: does not mention return value, but acceptable given simplicity.
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?
Adds default behavior information ('defaults to current org') not present in the input schema description, which only states 'Organisation ID (optional)'. Parameter semantics enhanced with practical usage context.
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?
Clearly states it resets the public key for an organisation and generates a new key. Distinguishes from sibling tools like get_organisation_public_key and return_identity_public_keys by the action 'reset'.
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?
Implies usage for resetting a public key but does not provide explicit when-to-use or alternatives. No exclusion guidance or comparison with related tools.
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, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds value by explaining the specific output (settings with required fields, defaults) and the default behavior for the companyId parameter. It does not contradict annotations and provides useful context beyond what annotations offer.
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 extremely concise: two sentences plus a parameter list. It front-loads the core purpose and provides essential details without any fluff. 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?
Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It explains what the tool returns, the parameter, and default behavior. No gaps remain for the agent to correctly invoke and understand the tool.
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 coverage is 100%, so baseline is 3. The description goes beyond the schema by stating that the companyId defaults to the authenticated company, which is additional semantic information that helps the agent understand parameter behavior.
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 ('returns'), the resource ('settings and defaults needed for creating consignments'), and the scope ('for a company'). It effectively distinguishes this tool from the many other 'get_consignment' siblings by focusing specifically on creation settings.
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 used for retrieving settings before creating a consignment, but it does not explicitly state when to use it versus alternatives, nor does it mention any exclusions or when not to use it. The context provides enough differentiation from siblings to infer usage, but lacks direct 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 already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, so the description adds minor value by confirming it returns all identity providers and requires no parameters. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, no wasted words. First sentence states purpose, second states no parameters. Perfectly structured for a simple tool.
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 tool with no output schema, the description adequately covers what it does and its scope. All necessary information is provided for the agent to invoke it correctly.
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 no parameters, the schema provides all information. The description restates 'No parameters required', which is clear but does not add meaning beyond the schema. Baseline for 0 params is 4.
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 it returns all identity providers for the current user's organization, using a specific verb and resource. This distinguishes it from sibling tools like get_identity_providers_for_company and get_identity_providers_for_organisation, which target different scopes.
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 usage context by specifying 'for the current user's organisation' and 'no parameters required', but it does not explicitly state when to use this tool versus alternatives or mention any prerequisites or 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 indicate readOnlyHint=true, destructiveHint=false. The description adds value by specifying the returned content (carrier rate options, addresses, item details). No contradictions. No additional behavioral context needed.
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 well-structured with Args, Returns, and Examples sections. It is clear and front-loaded, though the Args section somewhat redundantly repeats schema info.
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?
No output schema, but the description explains the return value (full quote object with carrier rates, addresses, item details). For a simple get-by-ID tool, this is sufficient.
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% with both parameters described. The description in Args repeats the schema with minimal addition. Examples provide usage context, but the baseline is adequate.
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 it returns full details for a single quote by ID, including carrier rate options. This distinguishes it from sibling tools like machship_get_quotes (plural) which lists multiple quotes.
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 provides explicit when-to-use examples: 'Show me the full details for quote 456' and when you need carrier rates to pick one for a consignment. It implies when not to use (e.g., for listing quotes, use get_quotes).
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 readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it returns consignments with pagination and optional filters, which is consistent with a safe read operation. It does not contradict annotations and adds moderate context beyond 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?
The description is extremely concise: a single-line purpose followed by a clear list of arguments with types and brief descriptions. No fluff, and the most important information is front-loaded.
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?
While the description covers all parameters and purpose, it lacks details on the response format (e.g., whether it returns full consignment objects or summaries) and does not mention pagination behavior for large result sets. For a tool with no output schema, this is a notable gap.
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 coverage is low (33%), but the description explains all 9 parameters, including purpose for optional ones (e.g., 'Filter by carrier', 'Include sub-companies'). This adds significant value beyond the schema, though some parameter descriptions remain brief.
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 explicitly states 'Returns consignments created or updated within a UTC date range' and identifies the tool as 'Ideal for sync/polling workflows.' This clearly distinguishes it from siblings like machship_get_active_consignments or machship_get_completed_consignments which do not filter by modification time.
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 a clear use case ('sync/polling workflows') and implies when to use the tool. However, it does not explicitly mention alternatives or conditions when not to use it, despite the presence of many related sibling tools.
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 destructiveHint=false, so the description's simple statement 'Returns available routes' is consistent but adds little beyond that. It does not disclose any additional behavioral traits like result limits or performance characteristics.
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 extremely concise, with two sentences plus an Args section. It front-loads the core purpose and then immediately details the parameter. No unnecessary 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?
While the parameter is well-described and annotations cover safety, the description lacks any information about the return value format (e.g., an array of routes). Given the tool's simplicity and the presence of a single route sibling, this is a minor gap but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the schema by stating that the 'requests' array contains 'route request objects (same structure as single route request)', linking to an established structure and clarifying the parameter's composition. With 100% schema coverage, this is highly informative.
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 it returns available routes for multiple shipment requests, using a specific verb ('Returns') and resource ('routes'). It distinguishes from siblings by explicitly mentioning 'batch' and 'bulk rate shopping', contrasting with the single route tool (machship_get_routes).
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 implies usage for bulk rate shopping across multiple shipments, providing clear context. However, it does not explicitly state when not to use or name alternatives, though the sibling tool name (machship_get_routes) is 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 annotations (readOnlyHint, idempotentHint, etc.), the description adds critical behavioral traits: the silent omission of unmatched SKUs and the restriction to 'standard items only'. This provides essential context for correct usage and error handling, fully leveraging the description's role to complement structured fields.
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 extremely concise at 4 sentences, front-loaded with the core purpose and constraints. Every sentence adds value: purpose, behavioral detail, and parameter listing. There is no fluff, and the structure (summary then args) is clear and scannable.
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 no output schema, the description adequately covers return behavior (list of items, silent omission of unmatched SKUs) and constraints (standard items, max 100). For a read-only batch lookup tool, this is sufficient for an AI agent to understand its function and handle results. A perfect score would require explicit mention of the return format or error scenarios.
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%, so the baseline is 3. The description repeats parameter meanings from the schema but adds no new semantic detail beyond 'standard items only' (which relates to items, not parameters). No additional constraints or formatting guidance are provided, so it meets but does not exceed the baseline for parameter semantics.
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 ('Returns'), resource ('list of saved items'), and criteria ('matching any of the supplied SKUs'). It also distinguishes from siblings by specifying 'standard items only' and the batch nature (max 100 SKUs), making it easy to differentiate from single-item lookup tools like machship_get_item_by_sku.
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 explicit guidance on detecting misses: 'SKUs that don't match any item are silently omitted — compare returned Sku values against your input.' It also implies that this tool is for standard items only, hinting that complex items require other tools. However, it does not explicitly state when to prefer this over alternatives or list exclusions, keeping it from a perfect score.
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 that the tool validates the key, which is behavioral context not covered by annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with a clear purpose sentence followed by an optional Args section. No unnecessary 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 lookup tool with annotations covering safety, the description is sufficient. It lacks details on return structure and error handling, but the basic functionality is clearly communicated.
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 schema already describes the parameter as 'Organisation public key'. The description's Args section repeats essentially the same information without adding new meaning.
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 validates a public key and returns organisation details. The verb 'validates' and 'returns' specify the action and resource, and it distinguishes from siblings like machship_get_organisation_public_key.
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 says 'Use this to verify a partner's public key before linking.' This provides clear context and timing for when to use the tool.
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 aligns with annotations (readOnlyHint=true) by stating it does not actually consolidate, and adds the preview step context. No behavioral traits beyond annotations are contradicted.
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 concise with two sentences and a parameter line, front-loaded with the main action, and contains no fluff.
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 simple parameter and annotations, the description adequately explains purpose and behavior. Minor lack of return value details, but reasonable for a preview tool.
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 description adds examples of parameter keys (companyId, carrierId, etc.) beyond the schema's generic description, enhancing understanding of the 'options' object.
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 'groups consignments' and the resource 'for consolidation', and distinguishes itself as a preview step before actual consolidation, differentiating it from tools that perform consolidation.
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 indicates this tool is a preview step before consolidation, but does not explicitly mention when not to use it or name alternative tools for actual consolidation or other grouping purposes.
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 non-read-only and non-destructive. The description adds value by detailing the behavior of omitted fields being set to null, which is crucial for understanding the tool's effect.
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 concise with two sentences and a bullet list. It front-loads the key behavior and efficiently conveys parameter details without extraneous 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 12 parameters and no output schema, the description covers core behavior and field requirements. It could mention the expected response (e.g., updated identity), but is otherwise adequate.
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 coverage is 58% (descriptions for 7 of 12 parameters). The description lists all parameters with brief context, specifies required vs optional, and explains the null-setting behavior, compensating for uncovered params.
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 'Updates properties on an identity', using a specific verb and resource. It distinguishes itself from sibling tools like machship_create_identities and machship_delete_identities by focusing on 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 guidelines: all fields except password are required, omitted fields are set to null. It implies use when updating an existing identity, but does not explicitly state prerequisites like having an existing identity ID.
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 cover read-only, non-destructive, idempotent, open-world. Description adds return structure detail, but no further behavioral traits. 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?
Front-loaded with purpose, then Args, Returns, Examples. No unnecessary words; 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?
With 2 parameters and no output schema, description provides detailed return structure example and usage context, making it complete for selecting and 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?
Schema covers 100% parameters with descriptions. Description lists same info and adds return structure context, but no new parameter semantics beyond 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 states it returns carriers, accounts, and services for a company. Examples show when to use, differentiating from sibling tools like get_companies.
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?
Explicit guidance: call before creating consignments/quotes, and don't use for company list (use get_companies instead). Examples help.
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 readOnly and idempotent. Description adds useful behavioral details: paginated (max 200 per call), date range filter, and carrier filter. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise and well-structured with sections for Args, Returns, and Examples. Every sentence adds value, and the most important information is front-loaded.
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 8 optional parameters and no output schema, the description provides a clear return structure (array of objects with fields) and covers pagination, filtering, and output format. It is complete for this type of list endpoint.
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 has 50% coverage (4 out of 8 parameters have descriptions). The description adds explanations for all parameters, including defaults and formats (e.g., ISO 8601 for dates, enum for response_format), compensating for missing 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 states it returns a paginated list of manifests for a company, defining a manifest as a carrier pickup booking. This is distinct from other sibling tools that deal with consignments, quotes, etc.
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?
Description provides examples of when to use (list today's manifests, need manifestId for PDF). However, it does not explicitly state when not to use or mention alternative tools, though the 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?
Annotations indicate readOnlyHint=true, destructiveHint=false. The description adds context by stating the return includes 'rates, ETAs' and mentions the single shipment scope. While it doesn't detail every behavioral trait, it complements the annotation well without 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 concise, uses a clear 'Args:' section, and front-loads the core purpose. Every sentence adds value, and the structure is easy to parse.
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?
No output schema exists, so the description should describe the return value. It mentions 'list of available freight routes and carrier services (rates, ETAs)' which gives a basic understanding, but could be more detailed about the structure of each route object. Overall, adequate given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description breaks down the 'request' object beyond the schema's brief description, listing explicit fields like companyId, fromSuburb, items with weight/dimensions, and optional despatchDate. This adds significant meaning 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 'Returns a list of available freight routes and carrier services for a single shipment request' and the title 'Get Available Routes' directly conveys the purpose. It distinguishes itself from siblings like machship_get_routes_batch and machship_get_routes_complex_items by specifying 'single shipment request'.
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 explicitly says 'Use this to find all carrier options (rates, ETAs) before creating a consignment', providing clear guidance on when to use the tool. It does not explicitly state when not to use it or mention alternatives, but it sufficiently orients the 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?
Annotations already declare readOnlyHint and idempotentHint. Description adds further details: returns up to 10 results, shows output format options, and describes return fields. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections: purpose, use case, args, returns, examples. Each sentence adds value, no redundancy. Appropriate length for the tool's complexity.
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?
Despite no output schema, description explicitly documents return object structure (id, suburb, postcode, state, country). Together with schema and annotations, it covers all necessary information for correct invocation and interpretation.
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 coverage is 100%, baseline 3. Description adds context beyond schema: explains 's' can be suburb+postcode combo, provides example 'Melbourne 3000', clarifies default for response_format. Adds meaningful usage guidance.
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?
Explicitly states it returns up to 10 locations matching a search string, describing verb (search), resource (locations), and scope (up to 10). Clearly distinguishes from siblings like get_locations_exact (exact match) and search_consignments (different resource).
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?
States when to use: lookup locationIds before creating consignments. Provides concrete examples of search queries. Could be improved by noting when to use alternatives like get_locations_exact for precise matches, but overall 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 discloses that the tool creates a quote (write operation) and returns the same format as machship_create_quote (array of rate options with cost and transit info). Annotations already indicate readOnlyHint=false, so the behavioral context is consistent. No contradictions, and the description adds useful return type information.
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 concise with a single sentence for purpose, followed by a structured Args/Returns section, and two concise usage examples. No wasted words, well-organized for quick parsing.
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 complexity (nested objects, many sibling tools), the description adequately covers what the tool does and when to use it. The return value is described by referencing machship_create_quote's output, which is sufficient. A more detailed output schema or description of the complexItems structure would increase completeness.
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 input schema has 100% coverage but only describes the 'quote' parameter generically. The description adds meaning by stating that the quote object uses a complexItems array instead of standard items, and gives examples of when to use. This provides context beyond the schema, though more detail on the structure of complexItems would improve it.
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 freight quote with complex item definitions (detailed packaging, dangerous goods, serialisation data). It uses a specific verb-resource pair and distinguishes itself from sibling machship_create_quote by specifying complex items.
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 provides two 'Use when' examples: when items have dangerous goods codes, serial numbers, or non-standard packaging, and when machship_create_quote returned a validation error about item structure. This gives clear guidance on when to use this tool versus alternatives.
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 indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds context that the tool performs a creation-like action but is non-destructive and intended for comparison. It clarifies the side effect (creating a quote) and the scope of returned data, which is helpful beyond the sparse annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with clear sections: action, purpose, parameter breakdown, return format, and examples. Every sentence adds value, and the structure makes it easy to parse.
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?
Despite no output schema, the description provides a sample return structure. It covers what the tool does, when to use it, what parameters are needed, and what results to expect. It is complete for its complexity and well-aligned with sibling context.
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 input schema has 100% coverage for the single parameter 'quote' with a brief description. The tool description elaborates on the structure of the quote object (companyId, addresses, items, optional filters) and includes a Returns section with example fields. This adds substantial 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 clearly states that the tool creates a freight quote and returns available carrier rates. It distinguishes from siblings by positioning this tool as a comparison step before consignment creation, and explicitly contrasts with machship_create_consignment in the 'Don't use' example.
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 provides explicit guidance: 'Use this to compare carrier prices and transit times before creating a consignment' and includes a specific 'Don't use when' scenario with an alternative tool (machship_create_consignment). This leaves no ambiguity about when to invoke this tool.
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 confirm read-only, idempotent, non-destructive behavior; description adds error handling (404 for invalid companyId) and return format, which is useful context beyond 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?
Well-structured with summary, args, returns, examples, and error handling sections; every sentence adds value and is front-loaded with main purpose.
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 listing tool, the description covers purpose, parameters, return structure, error cases, and usage guidance; no output schema needed as return format is specified.
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 coverage is 100%, but description repeats parameters with examples (default 'json' output) and links companyId to error handling, adding marginal value over 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?
Description clearly states 'Returns all quotes for a given company', uses specific verb and resource, and distinguishes from siblings like machship_get_quote and machship_create_quote through examples.
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?
Provides explicit 'Use when' and 'Don't use when' sections, names alternative tool (machship_create_quote) and complementary tool (machship_get_quote), and indicates required parameter (companyId).
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, destructiveHint=false, and idempotentHint=true, so the description is not burdened with basic safety. However, the description adds value by specifying that the tool returns session info including user details, company ID, and permissions, which is not in the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: the first states purpose, the second gives usage guidance, and the third clarifies return values. It is front-loaded and efficient with no extraneous 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 tool with no parameters, rich annotations, and a simple operation, the description covers purpose, usage, and return values. Although there is no output schema, the description adequately describes what is returned. The context is complete.
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?
There are no parameters (0 params, schema coverage 100%). The description correctly omits parameter info since none exist. Baseline for 0 params is 4, and the description does not need to add anything beyond what the schema 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 determines login status and retrieves session properties from Machship. It uses specific verbs ('determines', 'retrieves') and identifies the resource (Machship). Among the many sibling tools, this is uniquely a ping/auth check, so it is well-distinguished.
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 says 'Use this to verify authentication is working and to get the current user/company context.' This provides clear guidance on when to use it, and there is no need for when-not because no sibling tool serves the same purpose.
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 declare readOnlyHint=true, destructiveHint=false, etc. The description adds hierarchical filtering behavior, output format details, error codes (401, 403), and return object structure. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (Args, Returns, Examples, Error Handling). Slightly lengthy but every section is informative and 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?
Given the tool's simplicity (2 optional parameters, no output schema but description includes return structure), the description covers usage, outputs, errors, and examples thoroughly.
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 coverage is 100%, so baseline is 3. The description adds extra context: hierarchical filtering for atOrBelowCompanyId, default for response_format, and examples. This is meaningful 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 states the tool returns all companies accessible to the user and specifies the structure of returned objects. It distinguishes from siblings by mentioning that for carrier/service info, one should use machship_get_company_carriers instead.
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?
Includes explicit 'Use when' and 'Don't use when' examples with an alternative tool. Also covers error handling with specific HTTP status codes and suggested fixes.
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

Copy to your README.md:

[![machship-mcp MCP server](https://glama.ai/mcp/servers/devkindhq/machship-mcp/badges/card.svg)](https://glama.ai/mcp/servers/devkindhq/machship-mcp)

Score Badge

Copy to your README.md:

[![machship-mcp MCP server](https://glama.ai/mcp/servers/devkindhq/machship-mcp/badges/score.svg)](https://glama.ai/mcp/servers/devkindhq/machship-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/devkindhq/machship-mcp'

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