RepairDesk MCP by usefulapi

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

Goes well beyond the annotations: annotations only say destructive/non-idempotent/open-world, while the description discloses that a read-and-verify step precedes the write, that no status/timer/messaging/payment/delete endpoint is invoked, and that the write is attempted exactly once with an inspect-before-retry policy. This is exactly the operational context an agent needs before firing a destructive call.

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

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

Five terse sentences, front-loaded with the action and confirmation gate, followed by verification, side-effect scope, and retry policy. Nothing is redundant with the title or schema.

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

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

For a 4-parameter destructive write with no output schema, the definition covers prerequisites, side-effect scope, and failure handling. It omits any indication of what a successful response contains (note ID, ticket state) and any permission/auth requirements, which would complete the picture.

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

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

Schema coverage is only 25% (only 'confirm' is documented), so the description must carry weight; it clarifies that ticket_id and device_id are verified against the fetched ticket and implies the note text is the payload, but it says nothing about note length limits or ID format beyond what the schema patterns already enforce. Partial compensation for a coverage gap, so a mid score.

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

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

States a specific verb and resource ('Append an internal note (type0)') plus the underlying endpoint POST /ticket/addnote, which no sibling tool touches — all siblings are read/list operations. An agent can immediately distinguish this write tool from the surrounding read tools.

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

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

Gives a clear precondition ('after explicit confirmation'), describes the mandatory verification read of the ticket and its optional repair/device line ID, and prescribes behavior on an uncertain response ('inspect notes before retrying'). It does not name a specific alternative/sibling tool for the verification step, keeping it just short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond the raw endpoint: no statement about behavior when the ID doesn't exist, no mention of what the customer object contains, no caching or rate-limit notes.

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

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

Two short sentences, front-loaded with the action and with zero filler. Slightly terse given the information it omits, but nothing is wasted.

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

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

For a single-parameter read with full annotation coverage and no output schema, the essentials are present. Still missing is any indication of the response contents or failure mode, which matters since no output schema documents the return payload.

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

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

Schema description coverage is 0%, so the description carries the burden for customer_id. It does clarify that the ID originates from a customer or ticket lookup, which adds meaning beyond the bare pattern '^[1-9]\d{0,14}$', but it doesn't state the expected format or whether numeric-string vs number is accepted.

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

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

States a specific verb and resource ('Get one customer') and scopes it to a single record, which distinguishes it from the sibling repairdesk_list_customers. The endpoint path reinforces the resource, though there's no explicit contrast with the list sibling.

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

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

'using its ID from customer or ticket lookup' implies where a caller obtains the ID, which is genuinely useful context. However, it never states when to prefer this over repairdesk_list_customers or what to do when only a name/email is known.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint and clarifies that the payload is reference data (conditions, storage locations), but says nothing about the shape or size of the returned option sets.

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

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

Two short sentences with the meaningful content (what is read) front-loaded. The trailing "GET /inventory/additionalinfo" is mildly redundant with the tool name but is a compact, useful implementation anchor.

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

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

With zero parameters, no output schema and full annotation coverage, only a brief statement of what the options represent is needed, and the description supplies it. The only gap is the absence of a tell on how the returned options should be used downstream.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter semantics to explain and none is missing. The description correctly implies the call is unscoped and returns the full option set.

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

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

States a specific verb ("Read") and disambiguates the vague resource name "inventory options" into "item conditions and physical storage locations," which is the key value-add. It does not name a sibling, but none of the listed siblings overlap with this reference-data lookup, so differentiation is implicit.

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

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

The description never says when to call this (e.g., before filtering inventory by condition or location) or what alternatives exist, such as list_inventory for actual items. Usage is only inferable from the resource name.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the negation of writes is largely redundant reinforcement. The description adds no failure behavior (invoice not found), no auth requirements, and no indication of what the payload contains, which annotations alone don't cover.

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

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

Two short clauses: the operation and its non-goals first, the endpoint second. Every phrase carries information and nothing is buried or repeated.

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

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

For a single-parameter read with full annotation coverage and no output schema, this is nearly sufficient — the agent knows it is a safe, targeted read. The only real gap is return-value shape and not-found behavior, which the description leaves entirely to inference.

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

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

One required parameter with 0% schema description coverage, yet the description maps invoice_id onto the {Invoice-Id} path segment, conveying that it is an identifier rather than a filter. It adds no further semantics such as format hints (the numeric pattern lives only in the schema) or whether it is a RepairDesk internal ID.

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

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

States a specific verb and resource ("Read a single invoice") and the explicit HTTP path GET /invoices/{Invoice-Id}, which unambiguously separates it from a listing operation. It stops short of naming the sibling repairdesk_list_invoices, so the single-vs-many distinction is only implicit.

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

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

"Read a single invoice" implies the use case when an ID is already known, and "no payment or invoice creation occurs" bounds the scope. However, it never states when to prefer repairdesk_list_invoices or repairdesk_get_invoice_due over this tool, leaving the agent to infer the routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description's real addition is naming what comes back (amount and paid flag), which matters because there is no output schema, but it says nothing about behavior for a nonexistent or invalid invoice id.

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

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

Two short sentences, front-loaded with the return content and followed by the endpoint. Nothing is wasted or padded.

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

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

For a single-parameter read with no output schema, saying what is returned (amount and paid flag) plus the endpoint is nearly sufficient. Only error/not-found behavior is left unaddressed.

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

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

Schema coverage is 0%, so the description must carry the parameter burden. The path template GET /invoices/{Invoice-Id}/dueamount implies the single invoice_id parameter identifies the invoice, but it adds no format, origin, or constraint details beyond that implication.

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

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

States a specific verb and resource: read the outstanding amount and paid flag for one invoice. This distinguishes it from repairdesk_list_invoices by being single-invoice, but it never mentions repairdesk_get_invoice, so the boundary with that sibling is left to inference.

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

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

Usage is only implied by the name and endpoint – an agent can infer it is for checking whether an invoice is paid, but there is no explicit when-to-use clause and no statement telling the agent to prefer repairdesk_get_invoice when full invoice details are needed.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds useful behavioral context by noting that store ownership is checked, including transfers into the store, which helps an agent understand access scoping and potential authorization outcomes.

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

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

The description is compact and front-loaded: it first states what is read, then gives the endpoint, then notes an important ownership behavior. Every sentence adds useful information without repetition.

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

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

For a simple read tool with one parameter, the description gives sufficient context: it lists the ticket data returned, provides the endpoint, and discloses store-ownership checking. It does not cover error cases such as missing or invalid tickets, but no output schema exists and the core retrieval behavior is well described.

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

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

Schema description coverage is 0% for the single required ticket_id parameter. The description partially compensates by showing it as the {Ticket-Id} path parameter in GET /tickets/{Ticket-Id}, but it does not explain the expected ID format, source, or constraints beyond what the schema pattern already implies.

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

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

The description states a specific verb and resource: read a repair ticket. It also enumerates the ticket data returned, including summary, customer, repair devices, notes, line items, and invoice context, making the tool distinguishable from list-oriented siblings such as list_tickets.

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

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

The usage is implied by 'Read ticket summary...' and the endpoint GET /tickets/{Ticket-Id}, but the description does not explicitly say when to use this tool instead of siblings like list_tickets or get_customer. It gives enough context to infer retrieval of a single ticket, but no explicit alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by stating it returns one page and naming the underlying GET endpoint, but it does not discuss auth, limits, or result contents.

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

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

The description is three short sentences and front-loads the core action and scope. It contains no wasted language while conveying the key search purpose, pagination behavior, and endpoint.

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

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

For a tool with 10 optional parameters, low schema description coverage, and no output schema, the description is too thin. It says one page is returned, but it does not compensate for the missing parameter semantics or describe the return shape beyond pagination.

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

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

Schema coverage is only 20%, with 10 parameters and most undocumented in both schema and description. The description hints at customer/device context and assignment, but it does not explain keyword, status, page, pagesize, created_by, repairType, serviceType, or date-range semantics beyond what the schema already partially provides.

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

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

The description names a specific verb (Search) and resources (leads/appointments), and adds the customer/device context and assignment scope. It is clear enough to identify the tool, though it does not explicitly distinguish itself from sibling list tools such as repairdesk_list_tickets.

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

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

There is no explicit guidance about when to use this tool versus alternatives, no prerequisites, and no exclusions. The phrase 'Search leads/appointments' implies usage, but the agent must infer the selection conditions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds one real behavioral fact — "Returns one page" — signaling paginated results, plus a redundant endpoint reference. It omits defaults, maximum page size behavior, and whether a total count is returned, so it adds some value but not rich context.

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

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

Three short sentences, front-loaded with the useful search semantics, with no filler. The trailing "GET /customers." is redundant implementation detail that doesn't earn its place, but it costs little.

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

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

There is no output schema, so the description should describe the return shape, and "Returns one page" is the only hint — no mention of what a customer record contains or how paging terminates. For a four-parameter list tool with a documented safe-read annotation set, this is minimally adequate but leaves real gaps.

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

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

Schema description coverage is 0%, so the description carries the full burden and only partially discharges it: "keyword or referral source" maps to keyword and referredby, but page and pagesize are never mentioned or constrained (pagesize maxes at 100). Half the parameters remain undocumented in both schema and description.

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

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

The description names a specific verb and resource ("Search customer records") and states the filterable dimensions (keyword, referral source), which distinguishes it from the singular repairdesk_get_customer. It stops short of explicitly naming the sibling it is not, so 4 rather than 5.

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

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

Usage is implied by the two filter dimensions it names, which tells an agent this is a browsing/search entry point. There is no explicit statement of when to prefer it over repairdesk_get_customer (single-record lookup) or the other list_* tools, and no exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the underlying endpoint (GET /devices) and nothing about pagination, result caps, or filter combination behavior, so added value is modest.

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

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

Two short sentences with the resource and filter dimensions front-loaded; there is essentially no filler. The trailing 'GET /devices' is marginally redundant with the tool name but still cheap and informative for agents reasoning about the API.

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

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

With no output schema, the description should say what a result looks like (device model entries, IDs usable elsewhere) and whether the list is paginated or truncated. It says only 'device catalogue,' leaving the agent to guess at return shape and completeness.

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

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

Schema coverage is 0%, so both optional parameters (brand, device_name) are undocumented in the schema. The description partially compensates by identifying them as manufacturer/brand and device-name filters and hinting they are alternatives ('or'), but it does not clarify matching semantics (exact vs. substring), case sensitivity, or whether both can be combined.

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

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

States a specific verb (read/list) and resource (device catalogue) and names the two filter dimensions, which distinguishes it from siblings like list_parts or list_inventory. It does not explicitly contrast itself with any sibling, keeping it just below a 5.

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

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

The phrase 'by manufacturer/brand or device name' implies the tool is used to look up device models, optionally filtered, but there is no explicit statement of when to prefer it over related list tools or what happens when no filter is supplied. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description still adds real value by disclosing what is deliberately excluded (access PINs, permissions, private employee data, payroll), which tells the agent why some fields it might expect will be absent. Pagination and result-volume behavior remain unstated.

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

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

Three short clauses, front-loaded with the returned fields, then the omissions, then the endpoint. No filler and no repetition of the title.

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

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

There is no output schema, so enumerating the returned fields in the description is essential and is done precisely. For a zero-parameter, read-only list tool with annotation coverage, nothing an agent needs in order to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to clarify beyond confirming the call is unconditional. It correctly avoids inventing filtering options that the schema does not support.

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

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

States a specific verb (list) and resource (employees) and enumerates exactly which fields come back (staff ID, display name, role), plus the RAW endpoint. The resource is clearly distinct from every sibling (customers, devices, invoices, tickets), so no confusion is possible.

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

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

'For assignment lookup' hints at the intended use case, giving an agent an implied context for calling it. However, it never states when not to use it, whether there is a companion tool for a single employee, or what prerequisites exist. Usage is inferable but not guided.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by saying it returns the vendor's items list and that the endpoint documents pagesize but has no page parameter, which warns the agent about pagination limitations.

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

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

The description is front-loaded and compact, with the search behavior stated first and the pagination caveat following. The added 'GET /inventory' is minor but still relevant, and there is little wasted wording.

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

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

For a read-only list tool with annotations covering safety, the description gives enough to understand the search and pagination limitation. However, with no output schema and 0% schema description coverage, the undocumented missing_cost_price parameter and vague return description leave a meaningful gap.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains that keyword matches ID, name, or SKU and references pagesize, but it completely omits missing_cost_price, leaving one of three parameters undocumented.

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

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

The description uses a specific verb and resource: 'Look up inventory by ID, name or SKU in keyword,' which clearly states what the tool does and what the keyword field searches across. It does not explicitly differentiate from sibling tools such as repairdesk_get_inventory_options, but the purpose is still clear.

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

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

The description implies usage by explaining that keyword accepts ID, name, or SKU, so an agent knows how to search. However, it does not state when to use this tool instead of alternatives like repairdesk_get_inventory_options or repairdesk_list_parts, nor does it give explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered externally. The description adds real value by disclosing the pagination contract ('One page', page defaulting to 0) and the underlying endpoint, but says nothing about result volume limits, sorting, or what the response looks like.

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

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

At three short sentences it is compact and front-loads the resource description. The middle sentence 'One page (page defaults0)' is malformed (missing space, awkward phrasing) and the trailing 'GET /invoices' is a raw endpoint dump that adds little for an agent that cannot issue HTTP directly.

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

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

With seven optional parameters, 29% schema coverage and no output schema, the description leaves significant gaps: no pagination semantics beyond a default page, no indication of which filters combine or are ignored, and no sense of the return payload. For a list tool that an agent must page through, this is under-specified.

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

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

Schema coverage is only 29% (only from_date/to_date are documented), so the description has to compensate. It partially does: it clarifies that keyword searches invoice numbers and customers, that status relates to paid status, and that page defaults to 0. But pagesize, payment_method and the interplay between page and pagesize remain completely unexplained in both schema and description.

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

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

The description conveys that this returns invoice records with totals, paid status and balances, and names the endpoint (GET /invoices), so the resource is identifiable. However, it never states plainly that it lists invoices, and 'Search invoice numbers and customers' is ambiguous about whether customers are a searchable field or a returned entity. Nothing distinguishes it from siblings like repairdesk_get_invoice or repairdesk_get_invoice_due.

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

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

There is no when-to-use guidance at all: no statement about choosing this over repairdesk_get_invoice (single invoice) or repairdesk_get_invoice_due. The only usage-adjacent remark is 'One page (page defaults0)', which is pagination behavior rather than tool selection guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds only that this is a catalogue lookup against GET /networks; it says nothing about pagination, result size, or whether the list is tenant-scoped.

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

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

Two very short sentences with the action front-loaded and no filler. The 'GET /networks' fragment is minor redundancy but not enough to penalize heavily.

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

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

For a trivial no-param list tool with annotations covering safety, this is close to sufficient, but with no output schema the agent gets no hint about the shape or typical contents of the returned network entries, which matters for deciding whether to call it before list_devices.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline applies. The endpoint reference confirms no filtering options exist, which is mildly useful.

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

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

States a specific verb and resource: 'Read the device network catalogue', which tells an agent this returns the set of network options referenced by devices. It's distinguishable from siblings like repairdesk_list_devices or repairdesk_get_inventory_options, though it never explicitly contrasts itself with them.

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

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

No indication of when to call this versus the other list_* and get_*_options siblings, and no prerequisites or context about what the catalogue is used for downstream. The agent has to infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned field set and the underlying endpoint, but says nothing about result volume, pagination, sorting, or whether the whole parts catalog is returned by default — relevant for a zero-parameter list call.

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

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

Two telegraphic fragments, front-loaded with what the caller gets back. Efficient with no filler, though the bare 'GET /parts' endpoint note adds little for an agent that never constructs URLs.

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

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

With no output schema, the description usefully lists the returned fields, which partly discharges that burden. It still omits any sense of result size, pagination or ordering for a list endpoint that takes no filters, leaving the agent unable to predict response shape fully.

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

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

The tool takes no parameters (schema coverage 100% trivially), which sets the baseline at 4. The description correctly implies an unfiltered read with no arguments to supply, consistent with the empty schema.

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

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

The description uses the verb 'Read' on the resource 'parts' and enumerates the specific fields returned (names, SKU, stock, pricing), so an agent knows exactly what data this yields. It does not, however, distinguish this from the sibling repairdesk_list_inventory, which plausibly overlaps with a parts listing.

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

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

There is no statement of when to use this tool versus repairdesk_list_inventory or repairdesk_get_inventory_options, and no prerequisites or exclusions. The agent must infer from the name alone which of the several inventory-ish siblings to pick.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. Beyond that, the description adds only the raw endpoint string ('GET /repaircategories') and says nothing about result completeness, pagination, or whether the list is tenant-scoped — so it contributes almost no behavioral value over 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.

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

Two short sentences, front-loaded with the action and resource, with no filler. However, the second sentence is a bare endpoint path that consumes space without adding agent-relevant meaning, so it is not a model of economy.

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

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

This is a trivial zero-parameter read with annotations covering safety and no output schema, so the burden is low. Still, an agent gets no hint about the shape of the returned categories (id/name pairs) or whether the full set is returned, which would have been cheap to include.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The description correctly implies a no-argument call by not introducing any filtering concepts.

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

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

The description names a specific verb ('Read') and resource ('repair categories'), which cleanly separates it from the sibling list_* tools for tickets, customers, invoices, and so on. It stops short of saying what a category contains or whether the result is paginated, so it is clear but not fully specified.

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

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

There is no guidance on when to call this versus any sibling — no mention of using the returned categories as IDs for other operations, and no exclusions or prerequisites. The only usage signal is the resource name itself, which is implied rather than stated.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds only that results are scoped to the authenticated store, which is modest but real added context; nothing is said about ordering, completeness, or whether custom statuses are included.

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

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

Two short sentences with zero waste: the purpose is front-loaded and the endpoint follows as supporting detail. Nothing could be removed without losing information.

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

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

For a read-only, parameterless lookup with no output schema, the description conveys enough to invoke it correctly, and the phrase 'status names' implies the return shape. A brief note on per-store scoping being derived from configuration rather than an argument would make it fully self-contained.

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

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

The tool takes zero parameters and the description correctly introduces none, so there is nothing to mismap. Baseline 4 applies for a parameterless tool with 100% schema coverage.

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

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

Specific verb-plus-resource: it returns the store's available ticket status names, and the 'GET /statuses' endpoint confirms the exact backend resource. It is clearly distinct from sibling list_* tools (tickets, invoices, employees), though it never explains what a 'ticket status' is used for in this API.

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

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

No explicit when-to-use guidance, no mention that these status names are typically needed to filter or interpret repairdesk_list_tickets results, and no alternatives or exclusions given. The lookup purpose is only inferable from the phrase 'available ticket status names'.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior: it returns exactly one page and page defaults to 0. It does not explain result ordering or what default_order controls, which is the main behavioral gap.

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

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

Three short sentences with no filler, and the most useful facts (what you get back, how keyword works, pagination) come first. The typo 'defaults0' and the telegraphic style cost it a point but the size is appropriate.

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

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

With nine parameters, no output schema, and an undocumented enum, the description does too little: it never says what a page looks like beyond a loose field list, omits the 100-item page-size cap, and leaves sorting semantics opaque. For a primary listing endpoint used by most ticket workflows, this is under-specified.

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

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

Schema description coverage is only 22%, so the description needs to compensate and largely does not. It clarifies keyword and the page default, but status, created_by, assigned_to and especially the default_order enum ('0','1','2') are left completely unexplained — the agent cannot know which sort each value selects.

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

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

The first sentence names the concrete payload (ticket/order numbers, customer/device context, status, assignments) and the title plus 'GET /tickets' confirm this is a read/list tool. It is clearly a listing operation, but it never explicitly contrasts itself with the very similar sibling repairdesk_get_ticket, so the agent must infer that this returns collections rather than a single record.

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

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

'keyword searches the ticket list' hints at filtering, but there is no statement of when to choose this over repairdesk_get_ticket or repairdesk_list_statuses, and no exclusions or prerequisites. An agent gets no guidance on how to page through results or when to stop.

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