sortly

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

Annotations only give destructiveHint=true, so the description must carry behavioral weight; it does disclose the operation is a WRITE and names the backing endpoint (POST /api/v1/alerts). It does not cover permissions, alert-count limits, idempotency, or error behavior, which is a meaningful gap for a 7-param mutation.

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 core sentence is front-loaded and dense but readable, with the write flag and endpoint trailing as short fragments. The heavy parenthetical nesting of method names makes it slightly harder to scan than a bulleted breakdown would be, but there is 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 7-parameter write tool with no output schema, the description covers both operational modes and the required field pairing well enough to call it correctly. Remaining gaps are behavioral (auth, limits, failure modes) rather than structural.

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 100%, but the description adds cross-field coupling semantics that the flat schema does not express as clearly: which threshold_method values pair with which type, and that DateReminder needs custom_attribute_id plus an interval unit. The concrete example (quantity_less_than with threshold_value 5) is genuinely useful context.

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 stock alert on an item') and immediately enumerates the two supported alert shapes. It is trivially distinguishable from siblings like sortly_list_alerts or sortly_create_item, which target different resources.

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 tells the agent how to choose between the two modes (Quantity vs DateReminder) with concrete method examples. It does not name any alternative tool or state when-not-to-use (e.g., use list_alerts to inspect existing alerts), so it falls short of full routing 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 only supply destructiveHint=true and a title, so the description carries the behavioral burden. It does echo the write nature ('WRITE') and the underlying endpoint (POST /api/v1/items), confirming a mutating create. However it says nothing about what happens on duplicate names, permission/plan requirements, or what the call returns (no output schema exists), leaving meaningful behavioral gaps.

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 plus two short tags ('WRITE.', endpoint) — no filler, and the primary capability and its two modes come first. The telegraphic fragments are slightly terse but each earns its place by signaling mutation and the REST mapping.

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 create tool with nested objects and no output schema, the description covers the item/folder distinction and folder nesting but omits several notable optional groups (photos, min_quantity, secondary barcode, label symbology) and never indicates what a successful create returns, such as the new item id. Structure is adequate but not complete for the tool's complexity.

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% across all 15 parameters, so the schema already documents name, type, parent_id, custom_attribute_values and the rest. The description merely summarizes a subset (quantity, price, tags, custom fields, barcodes, measured quantity) without adding format or validation detail beyond the schema, so baseline 3 applies.

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

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

The description opens with a specific verb+resource ('Create a trackable item ... or a folder') and immediately disambiguates the two type values, which no sibling tool covers. An agent can tell it apart from sortly_update_item, sortly_move_item and the get/list siblings 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 by the description's scope ('Create ...'), and the nesting hint via parent_id gives one conditional behavior, but there is no explicit when-to-use vs when-not guidance and no named alternatives (e.g., update_item for modifications, move_item for relocation). Adequate but with clear gaps.

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

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

With destructiveHint=true already declared, the description still adds real behavioral context: the automatic job-folder creation, the initial not_started status, and the company-wide name uniqueness rule. It doesn't say whether the operation is reversible or what a duplicate-name attempt returns.

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 core action and side effects before the follow-up pointer. The trailing 'WRITE. Sortly: POST /api/v1/jobs.' is slightly redundant with the destructiveHint annotation but is short and harmless.

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 write tool with no output schema, the description covers the key gotchas (uniqueness, initial status, created folder, next step) and the schema covers all parameters. What an agent needs to call it correctly is essentially present.

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 7 parameters are already documented with types, lengths, patterns and item limits. The description only restates the uniqueness rule for 'name', adding 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?

States a specific verb and resource ('Create a job'), plus two non-obvious facts: a job folder is created alongside it and the job starts in not_started status. The resource is clearly distinguishable from the other create_* siblings (item, alert, purchase order).

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 routes the agent to the follow-up tool ('Then use sortly_pull_items_into_job to record the stock it uses'), which is genuine when-to-use guidance. It does not state when NOT to create a job or what to check beforehand beyond the uniqueness constraint.

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 carries most of the burden and does well: it declares WRITE semantics, that the record stays in draft with no stock/ordering effect, that totals are server-computed, and that a missing plan returns 402. It stops short of describing the response payload or whether the draft can be edited later.

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 fragments, front-loaded with the core action and status, with no filler. Slightly telegraphic ('WRITE. Sortly: POST /api/v1/purchase_orders.') but every clause conveys something actionable.

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-object create call with no output schema and thin annotations, the description covers the essentials an agent needs: draft semantics, computed fields, number auto-generation, plan gating, and mutation status. The only real gap is what the call returns (e.g., the new PO id) for follow-up calls.

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 baseline is 3, but the description adds meaning beyond the schema: auto-generation of purchase_order_number when omitted and the fact that amounts/sub_total/total are derived from line items rather than supplied. These are server-side behaviors the schema cannot express.

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+state ('Create a purchase order in draft status') and immediately clarifies that nothing is committed until later. Siblings are read/list tools for POs, so the create intent is unambiguous without opening any schema.

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

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

Gives clear context for when this is the right call (draft PO creation, requires Purchase Orders on the plan else 402) and notes the consequential follow-up step. It does not compare against an alternative creation path, but no sibling offers one, so the guidance is effectively complete.

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 useful context by naming the returned fields and the optional embedded associations, but says nothing about permissions, error behavior, or pagination.

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

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

Front-loaded with the core action and sized to one sentence plus an endpoint reference. The raw API path is slightly redundant, but 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?

For a read-only tool with no output schema, the description does the important work of enumerating the returned fields and the optional embeds, so an agent knows what it gets back. Missing only wildcard/not-found behavior, which is minor here.

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 both parameters are already documented in the schema. The description restates the item_id lookup and the include associations without adding syntax or format detail beyond what the schema provides — baseline 3.

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 (single item or folder), scoped by numeric id, and enumerates the returned fields. It clearly contrasts with list_items/search_items by the word 'single', though it does not name a sibling explicitly.

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

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

Usage is implied by 'by numeric id' and the optional include of custom field values and photos, which tells the agent how to enrich the fetch. There is no explicit when-to-use-vs-alternative guidance or exclusion against list/search siblings.

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, so the bar is lower, yet the description still adds value: it discloses the returned content set and clarifies that folder_id is where pulled items sit and that the record carries a version required for updates. It stops short of error/not-found behavior, but for a single read that is a minor 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?

Front-loaded single sentence plus an endpoint mapping; every clause carries return-field information. The 'Sortly: GET /api/v1/jobs/{job_id}' tail is mildly redundant but cheap.

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

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

For a one-parameter read tool with annotations covering safety and no output schema, the description adequately conveys purpose and returned fields. Only explicit sibling routing and error behavior are 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?

One parameter with 100% schema description coverage, so the schema already documents job_id fully. The description adds no syntax or constraint detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Fetch a single job') and enumerates the notable fields returned (status, folder_id, dates, notes, custom fields, version). Scope 'single' implicitly distinguishes it from the list_jobs sibling, though no sibling is named explicitly.

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

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

Usage is implied by the required job_id, and the phrase 'the version needed for updates' hints that this is called before an update, but there is no explicit when-to-use/when-not guidance or routing to list_jobs / get_item alternatives.

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 safe-read profile is covered. The description adds real value beyond that by disclosing the returned content — line_items with quantity vs received_quantity, vendor, addresses, charges, totals, version — which matters because no output schema exists. It omits error behavior (e.g. invalid id) but that is a minor 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?

Two sentences, no filler, with the core action and return payload front-loaded and the HTTP endpoint relegated to a compact trailing reference. Every clause earns its place.

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

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

With no output schema, the description usefully enumerates the fields a caller receives, which is the main thing an agent needs to decide to call it. It could have noted failure behavior for a non-existent id, but for a simple single-parameter read it is essentially 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 required integer purchase_order_id, so the schema does the heavy lifting. The description confirms the id maps to the path parameter but adds no format, range, or lookup semantics beyond what the schema already states.

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 purchase order") and enumerates the returned sub-resources, so an agent can tell it apart from list/sibling read tools. It stops short of naming the alternative tools (e.g. sortly_list_purchase_orders) explicitly, so sibling differentiation is implied rather than stated.

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 word "single" implies this is the lookup-by-id tool versus the list variant, but there is no explicit when-to-use guidance, no mention of when a list or receive-status call would be preferable, and no stated prerequisites. Usage is only inferable from the singular scope.

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 rest and does so well: it enumerates the three possible status values, explains that line ids are bucketed into received/pending/failed with failure reasons, and discloses the 404-until-first-receipt behavior. It stops short of mentioning auth scoping or freshness/refresh semantics, so it is not 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 tightly packed sentences lead with the outcome and status vocabulary, then the caveat, with no wasted words. The trailing API path is mildly redundant for an agent but serves as a useful anchor for debugging.

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 must describe return values, and it does: status enum, line id buckets, failure reasons, and the 404 case. For a single-parameter read-only tool this is nearly complete, missing only scoping or freshness context.

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 description adds nothing about purchase_order_id beyond what the schema already says ('The purchase order's id.'). With schema description coverage at 100% for a single parameter, the schema does the entire job and 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 exact payload (pending/completed/failed status plus received, pending and failed line ids). This is clearly distinguishable from sibling sortly_get_purchase_order, which would only return the PO itself.

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: an agent can infer this is the tool for checking receipt progress, and the '404 until something has been received' note tells it when the endpoint yields nothing. However, it never explicitly contrasts with sortly_get_purchase_order or says which to call when, so the routing guidance is left to inference.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds genuine value by naming the output discriminator (is_fired shows which alerts have triggered), but says nothing about result volume, pagination behavior, or whether firing is one-way — gaps for a list tool with no output schema.

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

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

A single front-loaded sentence that leads with the resource and its variants; nothing is wasted. The trailing 'Sortly: GET /api/v1/alerts.' is mildly redundant endpoint boilerplate, which keeps it short of 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 does the right thing by explaining the is_fired return field. It falls short only on result-set semantics — expected volume and how page/per_page should be used in practice — which an agent invoking a paginated list tool would benefit from.

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

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

Schema description coverage is 100% and both page and per_page are documented there with a stated default, so the schema carries the full parameter burden. The description adds no pagination or filtering syntax beyond that, making 3 the correct baseline.

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

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

States a specific verb (List) and resource (alerts), and disambiguates the two alert kinds it can return — stock/Quantity vs. date/DateReminder — so an agent knows exactly what set it gets. The mention of the is_fired field further pins down the payload's meaning.

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 'the quick way to find low-stock items' implies a use case, which is more than nothing, but there is no explicit when-to-use vs. when-not guidance and the sibling sortly_create_alert is never referenced. Usage 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?

readOnlyHint=true already declares the safe-read profile, so the bar is lower. The description still adds value by disclosing the shape of each returned custom field (id, name, type, applies_to), which no annotations or output schema provide, plus the underlying endpoint. Pagination behavior is left to 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?

Three compact clauses, front-loaded with purpose, then the workflow trigger, then the endpoint. Every sentence earns its place with zero 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 parameterless-required, read-only listing tool with full schema coverage and a covering annotation, nothing is missing. It even tells the agent why it exists (to obtain custom_attribute_id before a write).

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

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

Schema description coverage is 100% and both page/per_page are documented there with defaults and ranges. The description adds no parameter detail, so the baseline of 3 for schema-does-the-work 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 (List) and resource (the account's custom fields), and enumerates the returned fields (id, name, type, applies_to). No sibling tool deals with custom fields, so the agent can distinguish it immediately from the item/job/alert 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 an explicit sequencing directive: 'Call this before writing custom_attribute_values to get the right custom_attribute_id.' That is a concrete when-to-use trigger. It stops short of naming when-not to use it or an alternative, but no alternative exists for this lookup.

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 adds real value by disclosing ordering ("newest first") and the pagination contract (meta.next_page_url / total_pages), which the agent cannot get from annotations alone. It stops short of describing response shape or default page size behavior beyond what's in the schema.

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

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

Three tight sentences with the default behavior, the parameter-driven variations, and the pagination contract front-loaded in that order. The trailing "Sortly: GET /api/v1/items" is a compact, useful endpoint anchor. Nothing wastes space.

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

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

With no output schema, the description carries the burden of telling the agent how results come back, and it does so via the pagination fields and ordering. The remaining gap is the absence of any note about what a result entry looks like or how embedded associations (include) change the 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 100%, so the schema already documents page, per_page, include, folder_id and include_subfolders. The description reinforces the folder_id/include_subfolders interaction and the root-level default, but adds no format or syntax detail the schema lacks — baseline 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+resource ("List items and folders") plus ordering ("newest first") and hierarchy semantics. It is clear what the tool returns, but it never names the sibling it must be distinguished from — sortly_search_items or sortly_list_recently_updated_items — so the boundary between plain listing and searching 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?

The description explains invocation modes well (default root, folder_id for direct contents, include_subfolders for nesting), which is genuine context. However, it gives no when-to-use guidance relative to alternatives like sortly_search_items, so the agent must guess whether to list or search when both are available.

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 the description adds real behavioral context: default ordering (most recently updated first) and the pagination signal (meta.pagination.has_next). It stops short of describing auth scope or rate limits, but for a read-only list this 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?

One compact sentence front-loads the verb, the object definition, ordering, and filters, followed by a short pagination note and the endpoint. 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?

With no output schema, the description usefully names the pagination field an agent needs to continue paging, and all six params are schema-documented. Minor gaps remain around response shape beyond pagination and permission requirements.

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 six parameters are already documented in the schema; the description only acknowledges name-prefix and status filtering plus the default sort. Baseline 3 applies since the schema carries the semantics.

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

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

States a specific verb+resource ('List jobs') and even defines the domain object ('work orders that pull stock out'), plus the underlying endpoint GET /api/v1/jobs. This clearly separates it from the singular sortly_get_job and the create/pull/return job 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?

The description implies usage by listing filterable fields (name prefix, status) and pagination, but never says when to reach for this over sortly_get_job or a search tool, nor any prerequisites. Usage is inferable from the name but not 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 only declare readOnlyHint=true, so the description adds real value: the default sort order, the field set that is omitted from results, and the 402 plan-gating failure mode. It does not cover pagination behavior or result shape, which keeps it short of a 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?

Three tight sentences, front-loaded with purpose and default behavior, then the omission/routing caveat, then the auth/plan constraint. Every clause earns its place; 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?

No output schema exists, so the description usefully declares which fields are excluded from the listing and points to where to get them, plus the plan prerequisite. What remains thin — pagination defaults and total-count behavior — is covered by schema-level parameter descriptions.

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 per-parameter descriptions, defaults and enum hints, so the schema does the heavy lifting. The description only reinforces filtering and default ordering, adding little syntax or format 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 and resource (list purchase orders) plus default ordering ('most recently updated first') and the filter dimensions (PO number, status). It also names the sibling it is not — sortly_get_purchase_order — so an agent can distinguish the two without opening schemas.

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 routes the agent to sortly_get_purchase_order when notes, terms, sub_total or line_items are needed, and warns that Purchase Orders must be on the plan (else 402). It does not state when-not to use it beyond that single alternative, but the context needed to choose is clear.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context: the default behavior when updated_since is omitted and the underlying endpoint. It does not describe pagination, rate limits, or return format, but with annotations carrying safety, a 3 is appropriate.

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

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

Two sentences, front-loaded with the core purpose and the key differentiating behavior. The endpoint note is brief and non-essential but doesn't detract. Every sentence earns its place.

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

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

For a six-parameter read-only list tool with no output schema, the description covers the essential purpose, the critical default behavior, and the endpoint. It omits return format and pagination details, but those are either standard or covered by schema descriptions. Slightly incomplete for an agent needing full behavioral context.

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 six parameters are fully documented in the schema. The description only indirectly references updated_since and doesn't add syntax or format details beyond what the schema provides. Baseline 3 when schema does the heavy lifting.

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

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

The description states a specific verb (list), resource (items and folders), and scope (changed since a Unix timestamp), and explicitly contrasts with sortly_list_items when updated_since is absent. An agent can distinguish this from sibling list tools without opening schemas.

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 clearly frames the tool as the incremental-sync read ('what moved since yesterday?') and notes the fallback behavior without updated_since, which implies when to use it. However, it stops short of explicit when-not or alternative recommendations (e.g., 'use sortly_list_items for full snapshots').

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 read-only nature is covered structurally; the description additionally discloses the underlying endpoint (GET /api/v1/units) and enumerates the returned fields. It does not cover permissions or pagination, but for a simple reference-list call those omissions are minor given the annotation coverage.

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 a single, front-loaded sentence that states the resource, the useful return fields, the practical purpose, and the API route without any wasted words. Every clause contributes either identification or invocation context.

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

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

There is no output schema, so the description carries the burden of explaining return values, and it does so by naming unit_name, unit_type, and scale. Combined with the usage note about measured_quantity and purchase-order lines, an agent has everything needed to call and interpret this simple reference-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?

The tool takes zero parameters, so there are no parameter semantics for the description to clarify. The baseline for a zero-parameter tool is 4, and the description correctly does not invent any parameter behavior.

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 ('List') and resource ('units of measure available to the account'), and the parenthetical specifies exactly what each returned unit contains. It is clearly distinguishable from sibling list tools like sortly_list_items or sortly_list_purchase_orders because it names the distinct resource and its fields.

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 a concrete use case: these units are 'the values measured_quantity and purchase-order lines expect,' which tells an agent when to consult this tool rather than guessing valid unit names. It does not explicitly name alternatives or exclusions, but the context is strong enough to route usage correctly.

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 carries the real burden — and it does: it discloses the split-item-with-same-sid outcome of partial moves, the merge-at-destination rule, that the returned id is the destination's, and the undo path. That is exactly the consequence information an agent needs before 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?

Dense and front-loaded: purpose and scope first, then the three behavioral outcomes, then the undo hint and the WRITE flag plus endpoint. Every sentence carries distinct information with no 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 destructive 4-parameter write with no output schema, the description supplies the mutation outcomes, the semantics of the returned id, and the recovery path. Nothing material 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: 'some or all of an item's quantity' clarifies how the quantity parameter interacts with the partial/full move behavior, and the merge rule relates the returned id to the destination. It stops short of documenting leave_zero_quantity explicitly.

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 — moving an item's quantity to another folder — and explicitly scopes it to items only, pointing folder relocation at sortly_update_item instead. An agent can distinguish this from siblings like sortly_update_item 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?

Explains the operational contexts well: partial move splits a new item, full move relocates, matching destination merges, and undo is done by moving back. It names the sibling for the folder case, but does not state when to prefer this over recreating/updating an item, so exclusions beyond folders are implicit.

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?

Adds substantial behavior beyond the lone destructiveHint annotation: a 100-item cap, independent per-item processing, partial failures still returning 200, a mandatory check of data.errors, and a 403 on completed jobs. This is exactly the kind of mutation semantics an agent cannot get from structured fields. No contradiction with destructiveHint=true.

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, then limits, error semantics, undo route, failure mode, and endpoint. Every sentence carries distinct information with no padding.

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

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

With no output schema, the description compensates by describing the response contract (data.errors, 200-on-partial-failure) and the auth/state failure (403 on completed jobs). An agent has everything needed to call it and interpret the result.

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 per-field descriptions for item_id, quantity, item_version, leave_zero_quantity, notes, and job_id. The description adds no parameter-level meaning beyond that, 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+resource with scope: 'Move quantities of existing items (from any folders) into a job's folder.' It also clarifies the domain meaning ('how usage on a job is recorded'), which separates it from sortly_move_item without needing 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?

Names the inverse operation ('Undo with sortly_return_items_from_job') and an explicit exclusion ('Returns 403 on a completed job'), which tells the agent when it cannot use this tool. It stops short of contrasting with sortly_move_item, so a choice between the two is still inferred.

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, which the description reinforces with 'WRITE.' It goes beyond that by disclosing non-atomic behavior ('items are processed one by one') and instructing the agent to inspect data.errors for partial failures, plus a 100-item cap. Doesn't cover permissions or reversibility.

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 dense sentences: destination default and limit front-loaded, failure-handling guidance and write semantics follow, and the HTTP endpoint is compactly appended. No wasted text.

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 destructive mutation with no output schema, the description covers direction, destination default, batch limit, and partial-failure handling. Only auth/permission expectations are missing.

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

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

Schema coverage is 100%, so all three parameters are already documented. The description restates destination_folder_id defaults and the 100-item ceiling, adding no meaning beyond the structured fields.

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 ('Move items off a job's folder back into inventory') with the direction made explicit, which cleanly distinguishes it from the inverse sibling sortly_pull_items_into_job. An agent can identify the operation 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?

Use is implied by the described direction and destination default ('All Items if omitted'), but no explicit when-to-use/when-not guidance or named alternatives are 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?

Annotations only supply readOnlyHint=true; the description adds genuine context by flagging the read-only-but-POST quirk and by explaining the pagination protocol (resend the same arguments with the next page number), which the schema does not convey. It still omits rate limits and what the response contains.

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: purpose first, scope second, behavioral caveat plus pagination last. No filler and the API mapping is compressed into a single trailing clause.

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 eight-parameter, no-required-arg search tool whose schema is fully documented and whose annotations cover safety, the description covers purpose, scoping, and pagination adequately. Only the shape of returned results is unaddressed, and no output schema exists to cover it.

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 eight parameters are already self-documenting; the description only restates the type restriction and folder scoping at a high level and adds no format or interaction detail. 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 (search) and resource (items and folders) plus the scoping dimension (name, folder). This is clearly distinguishable from siblings like sortly_list_items and sortly_get_item, which enumerate or fetch rather than search by name.

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 when to use it (name-based lookup with optional type/folder scoping) but never names an alternative such as sortly_list_items for unfiltered enumeration or sortly_get_item for direct ID fetch. Usage is inferred rather than 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 only supply destructiveHint=true, so the description carries most of the load and delivers: WRITE declaration, PATCH semantics ('Only the fields you pass change'), null-clears semantics, replace-not-merge semantics for tags and custom_attribute_values, plus the exact endpoint and 204 return code. No contradiction 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?

Three tight sentences, front-loaded with the core action and followed by overwrite semantics and the transport detail. No filler or restatement 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?

For a 15-parameter mutation tool with no output schema, the description covers what an agent must know: which fields change, how to clear a value, what gets replaced, write classification, and that success returns 204 with no body.

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 baseline is 3, but the description adds semantics the schema does not encode: partial-update behavior, null-to-clear, and wholesale replacement of tags/custom_attribute_values. That materially changes how an agent constructs the payload.

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 ('Change fields on an existing item or folder') and immediately disambiguates the mutation surface from sortly_move_item ('To move PART of an item's stock use sortly_move_item'). An agent can route between this and the sibling move tool without opening schemas.

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?

Concrete usage scenarios are given (stock count quantity update, rename, folder relocation via parent_id), which tells the agent when this tool is the right choice. It lacks an explicit negative case beyond the partial-stock-move carve-out, 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.