Sortly MCP by usefulapi

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

Annotations only carry destructiveHint=true, so the description has to do more lifting. It labels the operation 'WRITE' and gives the POST endpoint, which is useful but largely restates the write annotation; it says nothing about permissions, duplicate-alert behavior, or what happens to existing alerts. The mode-specific semantics (interval required only for DateReminder) add some real behavior 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?

Front-loaded with the core action, and the trailing 'WRITE. Sortly: POST /api/v1/alerts.' is compact. The single sentence is dense with parenthetical examples but no filler; a light trim of the nested parentheses would make it a 5.

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 7-parameter, 3-enum create tool with no output schema and only a destructive hint, the description covers the two creation modes and the type-dependent parameter pairings, which is the main thing an agent needs. It stops short of describing permission requirements or what the created alert returns (e.g., an id), which would round it out.

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

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

Schema description coverage is 100%, so the baseline is 3. The schema already explains that threshold_interval is 'Required for DateReminder; omit for Quantity' and that quantity_* methods pair with Quantity — the description largely repeats this. The only genuine addition is a concrete example ('threshold_method quantity_less_than with threshold_value 5').

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 (Create) and resource (alert), and splits the resource into its two supported flavors (Quantity stock alert vs DateReminder on a datetime custom field). It also gives the endpoint (POST /api/v1/alerts), so an agent can distinguish it from sortly_list_alerts without opening the schema. No explicit sibling naming, hence 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?

Guidance is implicit: the parenthetical examples show which threshold_method/threshold_value pairings belong to Quantity and which fields belong to DateReminder, which helps pick the right invocation. However, it never says when to reach for this tool versus sortly_list_alerts or how to verify an existing alert, and gives no exclusions or prerequisites.

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?

Only destructiveHint=true is annotated, so the description carries most of the burden. It does add useful signal beyond the annotations: the 'WRITE' marker and the concrete endpoint POST /api/v1/items. However it omits auth requirements, what happens on duplicate names, and whether the create is reversible, which matters 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.

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

A single dense sentence that front-loads the verb and the two type values, followed by the write/endpoint tag. No filler, though the trailing field enumeration is slightly redundant with the 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 15-parameter nested mutation with no output schema, the description covers the main shape but leaves gaps: no return-value expectations, no error behavior, and no note that the measured_quantity unit should come from sortly_list_units. Adequate but not complete.

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

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

Schema coverage is 100% with descriptions and enums for all 15 parameters, so the baseline is 3. The description nods at parent_id nesting and the label/barcode fields but adds no syntax or format detail beyond what the schema already documents.

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 (create) plus both resource types it produces (item/folder), with the parent_id placement scope named. It is easy to distinguish from siblings like sortly_create_alert, sortly_create_job, and sortly_update_item without opening the schema.

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

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

Creation intent is implied by the verb, and the description notes parent_id controls nesting, but it never states when to choose this over sortly_update_item or sortly_move_item, nor any prerequisites such as needing valid custom_attribute_ids or photo_ids first.

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 carry only destructiveHint=true; the description adds genuinely useful behavior beyond them — the created status (not_started), the side effect of creating a job folder, the company-wide name uniqueness constraint, and the WRITE/POST endpoint. It omits what happens on a duplicate name (error vs. silent) and what the response contains. Note the destructiveHint=true on a pure create is an imprecise annotation rather than a description contradiction, since the description explicitly frames this as a write.

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?

Four short sentences, front-loaded with what is created and its initial state, followed by the next-step pointer and the endpoint. The trailing 'WRITE.' is a compact mutability signal; nothing is bloated, though the endpoint notation is orientation-only.

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 create tool with no output schema, the description should tell the agent what comes back — most importantly whether the new job's id is returned so it can be fed to sortly_pull_items_into_job. It does not, and it is silent on duplicate-name failure behavior. The not_started status and folder side effect are well covered, but the return/next-step handoff is incomplete.

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

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

Schema description coverage is 100% — every one of the 7 properties is documented inline with type, length and format constraints. The description only restates the uniqueness rule (already in the name field description) and adds no syntax or edge-case detail, so this is the baseline case where the schema does the heavy lifting.

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

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

States a specific verb and resource ('Create a job') plus two distinguishing details: it also creates the job folder, and the job lands in not_started status. That is enough to separate it from sortly_create_item, sortly_create_alert and sortly_create_purchase_order without opening a schema.

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

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

Gives an explicit forward path ('Then use sortly_pull_items_into_job to record the stock it uses'), which is real routing guidance to a named sibling. It does not state when NOT to use this tool or whether a pre-existing job should be looked up first via sortly_get_job/sortly_list_jobs, so it stops short of full when/when-not coverage.

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 only supply destructiveHint=true, so the description is doing most of the work: draft-state semantics, server-computed sub_total/total from lines, auto-generated PO number, and the 402 plan requirement. The claim that nothing is ordered or stocked until later sits in mild tension with destructiveHint=true, though creating a draft record is still a write, so this is a nuance rather than a contradiction.

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

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

Three tight sentences, front-loaded with the draft-status constraint, then computation behavior, then the plan prerequisite. The "WRITE" marker and endpoint are compact signposts with no filler.

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

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

For a 10-parameter nested write tool with no output schema, the description covers the important surprises: draft semantics, computed totals, auto-numbering, and the 402 failure mode. It stops short of describing the response payload (e.g., the created PO id) or any permission/auth requirements, which the absence of an output schema leaves worth mentioning.

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 already 90%, so the baseline is 3; the description earns above baseline by telling the agent that amounts, sub_total and total are server-computed from line_items (so they must not be supplied) and that purchase_order_number can be omitted for auto-generation. It adds no detail for the address, charges, or vendor objects, which remain schema-only.

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

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

States a specific verb+resource ("Create a purchase order") plus the crucial qualifier "in draft status," which cleanly separates it from sortly_get_purchase_order / sortly_list_purchase_orders and from item/job creation siblings. An agent knows exactly what record type is being produced without opening the schema.

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

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

Gives clear when-to-use context: it creates a draft, nothing happens to stock or ordering until the PO is "moved on," and it requires Purchase Orders on the plan (else 402). It does not name a sibling alternative or the follow-up receive/update flow, so routing among siblings is left to inference.

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

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

Annotations declare only readOnlyHint=true, and the description adds real context beyond that: the underlying endpoint (GET /api/v1/items/{item_id}), the concrete payload fields returned, and the fact that custom fields and photos are conditional on the include argument. It does not cover failure behavior for a nonexistent id, but for a read tool the disclosure is solid.

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

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

A single dense sentence front-loads the verb, resource and identifier, followed by a short endpoint reference. Every clause (returned fields, optional embeddings) carries information; the field list is slightly list-like but not wasteful.

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 and only two parameters, listing the returned fields is exactly the right compensating detail, and the endpoint reference grounds the behavior. Only gaps are error/not-found handling and any folder-vs-item response difference.

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

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

Schema coverage is 100% and both parameters are already documented, so the baseline is 3. The description adds mild value by noting that custom field values and photos come back only 'optionally', which ties to the include enum, but it adds no format or syntax detail beyond the schema.

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

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

States a specific verb and resource ('Fetch a single item or folder by numeric id') and enumerates the returned fields, so the agent knows this is a point-read, not a list or search. It distinguishes itself implicitly from sortly_list_items/sortly_search_items via 'single' and 'numeric id', though it never names an alternative.

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

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

Usage is implied rather than stated: 'by numeric id' suggests the caller must already know the id, which is the natural contrast with search_items, but neither the when-to-use condition nor any exclusion is spelled out.

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, so safety is covered; the description goes further by disclosing the returned field set and, notably, that the response carries the version required for subsequent updates — a real concurrency/optimistic-locking signal. It stops short of stating auth needs, error behavior, or whether the version goes stale.

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

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

One dense, front-loaded sentence that puts the action first, followed by the API path reference. Efficient, though the trailing 'Sortly: GET /api/v1/jobs/{job_id}' is largely restating what the name and schema already convey.

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

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

No output schema exists, so the description must carry return-value information — and it does, listing the fields the agent can expect. Combined with the read-only annotation and the single well-documented parameter, nothing essential is missing for correct invocation.

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

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

One required parameter at 100% schema coverage, so the baseline is 3. The description adds only indirect meaning to folder_id (where pulled items sit) and says nothing about job_id beyond what the schema already states ('The job's id', positive integer).

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 ('Fetch a single job') plus an enumeration of the payload's contents (status, folder_id, dates, notes, custom field values, version), which cleanly separates it from the sibling list_jobs and the create/update/move job tools. An agent can identify the tool without opening the schema.

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

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

Usage is implied rather than stated: the mention of 'the version needed for updates' hints this precedes an update call, but no explicit when-to-use condition, prerequisites, or named alternative (e.g., list_jobs for enumeration) is given. Adequate but leaves routing to inference.

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

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

readOnlyHint=true already establishes the safe-read profile, but the description usefully adds the payload shape (quantity vs received_quantity on line items, plus vendor, addresses, charges, totals, version), which matters because no output schema exists. It does not disclose auth requirements, rate limits, or 404 behavior for a missing 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?

One dense sentence followed by the source endpoint; the return payload is front-loaded and nothing is padded. Slightly heavy as a single comma-separated enumeration, but every clause carries 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 single-parameter read tool with no output schema, the description compensates well by enumerating the returned fields. Missing only edge-case behavior (item not found, permissions) to be fully complete.

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

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

There is a single parameter with 100% schema description coverage, so the schema fully documents purchase_order_id. The description only restates it as part of the REST path, adding no new semantics — the baseline 3 applies.

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

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

States a specific verb (Fetch) and resource (a single purchase order), and itemizes what the response contains (line_items, vendor, addresses, charges, totals, version). The word 'single' implicitly distinguishes it from sortly_list_purchase_orders, though that sibling is never named.

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: 'a single purchase order' suggests the id-based lookup case versus a list operation. There is no explicit statement of when to use this instead of sortly_list_purchase_orders or sortly_get_purchase_order_receive_status, and no prerequisites or error conditions are mentioned.

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

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

Annotations cover the safety profile (readOnlyHint=true), and the description adds genuinely new behavioral context: the 404-until-received condition and the fact that only the most recent receive is reported. It stops short of noting auth requirements or rate limits, but goes well beyond the annotation.

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

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

Three dense, front-loaded sentences: what it reports, the failure condition, then the API mapping. Every sentence carries information and nothing is 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?

With no output schema, the description compensates by describing the return content — status values, received/pending/failed line ids, failure reasons — so an agent knows what to expect. For a single-parameter read tool this is complete.

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

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

Schema description coverage is 100% for the single purchase_order_id parameter, so the schema already carries the parameter meaning. The description adds nothing about id sourcing or format, so the baseline 3 applies.

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

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

States a specific verb and resource (report the most recent receive against a purchase order) and enumerates the outcome space (pending / completed / failed) plus the line-level breakdown. This clearly distinguishes it from sortly_get_purchase_order, which returns the order itself rather than its receive state.

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

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

It gives one useful usage constraint — 'Returns 404 until something has been received' — which tells the agent when this call is not yet valid. However, it never states when to prefer this over sortly_get_purchase_order or how it relates to the receive flow, so the guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description goes further by naming the two alert categories and explaining that is_fired marks already-triggered alerts, which is genuinely useful payload context not present in the annotations.

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

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

One compact sentence that front-loads the resource and alert types before the endpoint reference. Nothing is wasted and no sentence is redundant.

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

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

There is no output schema, so the description's explanation of the two alert types and the is_fired field meaningfully compensates. Pagination is left entirely to the schema, which adequately documents it, so the definition is nearly complete for a read-only list tool.

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

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

Schema description coverage is 100% with both page and per_page documented in the schema itself, so the baseline of 3 applies. The description adds no pagination or parameter syntax detail beyond what the schema already 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?

States a specific verb (List) and resource (stock/Quantity and date/DateReminder alerts), and the endpoint reference anchors it. It clearly separates itself from the sibling sortly_create_alert by being the read side of alerts.

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

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

'the quick way to find low-stock items' implies a use case, but there is no explicit when-to-use guidance or comparison against alternatives like sortly_list_items or sortly_get_item. Usage is suggested rather than specified.

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?

readOnlyHint=true already covers the safety profile, and the description goes beyond it by disclosing the tool's role as a lookup prerequisite for writing custom attribute values, which tells the agent why and when to call it. It does not describe pagination behavior, so it is not fully exhaustive.

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 compact sentences with no filler; the purpose and returned fields come first, and the usage instruction follows. The endpoint reference is appended rather than front-loaded, which is the right priority ordering.

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, but the description compensates by naming the fields returned and the key identifier (custom_attribute_id) an agent needs for downstream calls. Pagination defaults are covered by the schema, leaving only the response envelope shape unspecified.

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

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

Schema description coverage is 100%, so page and per_page are already documented in the schema. The description adds no additional meaning about pagination semantics, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('List the account's custom fields') and enumerates the returned fields (id, name, type, applies_to). This is clearly distinguishable from sibling list tools such as sortly_list_units or sortly_list_items, so an agent can select it without opening the schema.

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

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

Explicitly states the triggering condition: 'Call this before writing custom_attribute_values to get the right custom_attribute_id.' That is actionable workflow guidance, though it names no alternative tool to use when this one is not appropriate.

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?

readOnlyHint already declares the safety profile, and the description goes further by disclosing return ordering (newest first), pagination mechanics (meta.next_page_url / total_pages), and the underlying Sortly endpoint. Those are behavioral traits the annotations do not carry.

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

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

Four tight sentences with the ordering and default scope front-loaded, and no filler. The trailing endpoint citation is the only marginally expendable element.

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 names the pagination fields an agent must read and states ordering, which covers the main unknowns for a list tool. It leaves the relationship to the search/list siblings unresolved, which is the remaining 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 100%, so all five parameters are already documented; the description restates folder_id/include_subfolders behavior in prose but adds no syntax or default detail the schema lacks, and says nothing about page, per_page, or include. Baseline 3 applies.

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

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

States a specific verb and resource ('List items and folders') plus the ordering guarantee ('newest first'), which an agent can act on immediately. It does not distinguish itself from neighbors like sortly_search_items or sortly_list_recently_updated_items, which the description never names.

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

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

Gives clear scoping rules for folder_id and include_subfolders, so the agent knows how to bound the listing, but offers no guidance on when to choose this tool over sortly_search_items or sortly_list_recently_updated_items, which return overlapping data.

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 establish readOnlyHint=true, so the safety burden is lifted; the description goes further by disclosing the default ordering ('most recently updated first') and the pagination cursor location ('meta.pagination.has_next'), which is non-obvious behavior not present in the schema or annotations. It stops short of describing rate limits or result size limits.

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

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

Front-loaded and dense: the domain gloss, default sort, filterability and pagination mechanism each occupy a single clause. The trailing 'Sortly: GET /api/v1/jobs' endpoint reference is implementation detail of marginal value to an agent, which keeps it off a 5.

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

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

With no output schema, the description carries the return-shape burden and partially discharges it by naming the domain meaning of a job and the pagination envelope. It does not say what fields each job record contains or whether a total count is returned, but nothing needed to invoke the call 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?

Schema coverage is 100%, with each of the six parameters documented including defaults, ranges and enum values, so the schema does the heavy lifting. The description only restates the name-prefix and status filters and adds no syntax or semantics beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('List jobs') and immediately glosses the domain term as 'work orders that pull stock out', which an agent can use to reason about relevance. The list/collection scope clearly separates it from sortly_get_job and the create/update siblings.

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

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

Declares the filter surface (name prefix, status) so an agent can infer when this tool suffices, but never states when to prefer it over sortly_get_job for a single record, nor any prerequisite or exclusion. Usage is implied by the verb rather than explained.

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 only declare readOnlyHint=true, so the description carries the extra behavioral load and does so well: default sort order, the specific fields omitted from results (notes, terms, sub_total, line_items), and the 402 error condition. It stops short of describing pagination envelope or rate limits, so not a full 5.

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?

Four short clauses, zero filler: purpose and default order first, then the exclusion/alternative, then the plan gate, then the HTTP mapping. Front-loaded and every sentence earns its place.

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

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

With no output schema, the description compensates by naming the fields the list omits and pointing to the tool that returns them, plus the plan requirement. Together with 100% schema coverage, an agent has everything needed to call it and interpret the response.

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

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

Schema description coverage is 100%, so the schema already explains page, per_page, status, sort_by, sort_direction and purchase_order_number semantics. The description restates filterability by PO number and status but adds no format or syntax detail beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource (List purchase orders) plus the default ordering, and explicitly names the sibling sortly_get_purchase_order as the route for full record detail. An agent can distinguish this from the get/list siblings without opening either schema.

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

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

Explicit when-to-use routing: shallow list here, full detail via sortly_get_purchase_order. It also surfaces the plan prerequisite (Purchase Orders on plan, else 402), which is a gating condition an agent must know before calling.

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, so the safety profile is covered. The description adds one useful behavioral fact — the fallback to sortly_list_items when updated_since is omitted — but says nothing about pagination limits, auth, or ordering, so it is adequate rather than rich.

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

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

Front-loaded with the core action before the incremental-sync framing, and the endpoint tail is a compact reference. Slightly dense with a parenthetical example, 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?

Six optional parameters with full schema documentation and no output schema, so the description only needs to orient the agent — which it does, including the zero-argument default behavior. Ordering/sort semantics of the 'recently updated' result are the only unaddressed detail.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds value the schema does not carry: the documented consequence of omitting updated_since, and the fact that the result set spans both items and folders (relevant to folder_id/include_subfolders).

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 ('List items and folders changed since a Unix timestamp') and immediately labels its identity as the 'incremental-sync read', which distinguishes it cleanly from the sibling sortly_list_items. An agent can select it without opening either schema.

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

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

Gives clear usage context ('what moved since yesterday?') and names the sibling behavior it degrades to: without updated_since it behaves like sortly_list_items. It stops short of an explicit 'use X instead when Y' routing rule, so 4 rather than 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, so safety is covered; the description adds that this is a no-argument account-level listing, enumerates the response fields (unit_name, unit_type, scale), and identifies downstream consumers. It stops short of pagination, ordering, or permission requirements.

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

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

One dense sentence covering resource, fields and consumer, followed by the source endpoint. Front-loaded and free of filler.

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

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

With no output schema and zero params, the description carries the return-value burden and does name the three fields returned. It is almost complete but omits whether the list is paginated or how to interpret unit_type/scale values.

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

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

Zero parameters, so baseline is 4. The description instead characterizes the return fields and where those values are consumed, adding context the empty schema cannot provide.

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 (units of measure) scoped to the account, and names the returned fields. It is unambiguous against the sibling list, none of which deal with units of measure.

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

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

It implies usage by saying these are 'the values measured_quantity and purchase-order lines expect', which tells the agent when the data is relevant, but it names no alternative tool and gives no explicit when-not condition.

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 only declare destructiveHint=true, but the description discloses behavior well beyond that: a partial move splits off a new item with the same sid, a full move relocates the item, a matching destination item triggers a merge, the returned id belongs to the destination, and the operation is reversible by moving back. It also names the underlying endpoint, giving the agent a concrete mental model of a destructive write.

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

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

Front-loaded with the core action and scope before the edge-case semantics, then closed with a 'WRITE' marker and the endpoint. Dense but essentially waste-free; the merge/sid detail is long yet load-bearing, so it stays below a 5.

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?

Despite having no output schema, the description covers the return-value question (the returned id is the destination's) and the reversible-write path. Combined with 100% schema coverage and a destructiveHint annotation, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning beyond the schema by explaining what 'quantity' actually does (partial move splits a new item vs full move relocates) and what happens when the destination already holds a matching item. The folder_id root-omission and leave_zero_quantity defaults remain schema-only, so it doesn't fully saturate.

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 ('Move some or all of an item's quantity to another folder') and explicitly scopes it to items only, naming the sibling to use for the folder case ('relocate a folder with sortly_update_item parent_id'). An agent can distinguish this from sortly_update_item and the other sortly_* siblings without opening a schema.

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

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

Gives clear context for use (moving quantity between folders) and explicitly routes the folder-relocation case to sortly_update_item, plus an undo path ('move it back'). It doesn't spell out prerequisites or a full when-not list, so it falls 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?

Well beyond the destructiveHint annotation, it discloses the 100-item batch cap, that items are processed independently, that a partial failure still returns HTTP 200 so data.errors must always be checked, and that completed jobs return 403. These are exactly the runtime behaviors an agent cannot infer from 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.

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

Four tight clauses, front-loaded with the core action, then limits, then error handling, then undo, then the HTTP mapping. No sentence is filler and the most critical caveat (check data.errors) is emphasized with ALWAYS.

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 mutation tool with no output schema, the description covers the entire surface an agent needs: batch size, partial-failure semantics, the error field to inspect, the recovery tool, and the documented failure status. Nothing material is left undocumented.

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

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

Schema description coverage is 100% and every nested field (item_id, quantity, item_version, leave_zero_quantity) is documented in the schema itself, so the baseline is 3. The description only restates the items bound ('Up to 100 items per call') and adds no syntax or semantics beyond the schema.

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

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

The first sentence names a specific verb and resource — moving quantities of existing items into a job's folder — and adds scope ('from any folders') plus a conceptual gloss ('how usage on a job is recorded'). It is unmistakably distinct from siblings like sortly_move_item or sortly_create_item.

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

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

It states the operational context (recording usage on a job) and explicitly names the undo path via sortly_return_items_from_job, plus the failure condition (403 on a completed job). It does not, however, contrast against the closest sibling sortly_move_item, so the agent must infer when one is preferred over the other.

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 flag destructiveHint=true, but the description adds genuinely new behavioral context: items are processed one by one and the caller must inspect data.errors, implying partial-failure semantics. It also marks 'WRITE' and the underlying endpoint, going meaningfully 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.

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

Three dense, front-loaded sentences pack destination behavior, batch limits, error handling, and write semantics with no filler. Every clause carries information an agent needs.

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 write tool with no output schema, the description adequately covers the mutation target, batch constraints, destination default, and the need to check per-item errors. It is only slightly short on what the successful response contains, but the batch/partial-failure note compensates well.

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

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

Schema description coverage is 100%, so the schema already documents job_id, items, notes, and the nested item fields including destination_folder_id and item_version. The description only restates the destination_folder_id default, adding little beyond the schema, so the baseline of 3 is correct.

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 ('Move items off a job's folder back into inventory') with clear scope. It effectively describes the inverse of pull_items_into_job, but never names that sibling to make the routing explicit, so it stays at a 4 rather than 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?

It documents the destination default ('or All Items if omitted') and the 100-per-call cap, which imply usage conditions. However, it never states when to choose this over the sibling pull_items_into_job or any prerequisites, so usage is only implied.

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, but the description adds valuable context by explicitly noting 'Read-only despite being a POST' and describing the pagination mechanism. It stops short of covering authentication, rate limits, or return format.

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 core purpose, then critical behavioral notes, then the endpoint reference. Every sentence earns its place with no redundancy.

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

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

For an 8-parameter search tool with no output schema and readOnly annotations, the description covers purpose, scoping, pagination, and the POST/read-only nuance. It does not describe the shape of returned results, which would be helpful absent an output schema.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters thoroughly. The description only summarizes name, type, and folder scoping without adding syntax, defaults, or other meaning beyond the schema.

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

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

States a specific verb (Search) and resource (items and folders) with scope (by name, optionally limited to items/folders and specific folders). It distinguishes itself from siblings like list_items by focusing on name-based search, but does not explicitly name an alternative tool.

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

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

Gives clear context for when to use it: searching by name with optional type and folder scoping. It also explains pagination (send same arguments with next page number), though it does not state when not to use it or name a sibling alternative.

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

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

Annotations carry only destructiveHint=true, and the description shoulders the rest: partial-update semantics ('only the fields you pass change'), null-to-clear behavior, and that tags/custom_attribute_values are wholesale REPLACED. It also labels it WRITE, cites the PUT endpoint, and notes the 204 empty response – richly consistent with the destructive hint.

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

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

Front-loaded with the core action and examples, then the critical replacement semantics, then a compact 'WRITE. PUT ... (returns 204).' trailer. No sentence is wasted and the most decision-relevant facts come first.

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

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

For a 15-param mutation tool with 100% schema coverage and no output schema, the description covers the missing pieces an agent needs: replace-vs-merge behavior, null-clearing, and the no-content 204 return. Nothing essential to invoking it correctly is left unstated.

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

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

Schema coverage is 100%, so the 3 baseline applies, but the description adds real meaning the schema lacks: null clears nullable fields and tags/custom_attribute_values are replaced rather than merged. This clarifies mutation semantics for several of the 15 params beyond their one-line schema descriptions.

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

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

States a specific verb+resource ('Change fields on an existing item or folder') and immediately contrasts with the sibling operation (relocating via parent_id, with schema pointing to sortly_move_item). Concrete examples (stock count quantity, rename, relocate) let an agent distinguish it from sortly_create_item and sortly_move_item without opening a schema.

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

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

Offers clear contextual scenarios ('set a new quantity after a stock count, rename it, or relocate a folder') that signal when to reach for this tool, and the related move_item alternative is surfaced in the schema. It stops short of an explicit when-not statement in the description itself, so it is context rather than full routing guidance.

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