Search and read Sellsy companies, contacts, opportunities, invoices and tasks; create records.
Scored across 44 tools
Most tools pair a distinct resource with a clear action (create/get/list/search), and descriptions generally explain when to use each. There is some overlap between list_* and search_* for the same resources, plus a generic sellsy_search that overlaps entity-specific searches, but the descriptions make the intended boundaries mostly clear.
All tool names consistently use the sellsy_ prefix followed by a snake_case verb_noun pattern. The verbs (create, get, list, search) are used predictably across resources.
At 44 tools, the surface is very large for an MCP server and risks context bloat and tool-selection overhead. While the Sellsy CRM domain is broad, the set includes many near-parallel list/search variants per resource, pushing it well beyond a well-scoped tool collection.
Read and search coverage is strong across many Sellsy resources, and core CRM creates exist for companies, contacts, individuals, opportunities, tasks, and comments. However, there are no update or delete tools, and major resources such as invoices, estimates, orders, credit notes, items, and payments have no create operations, leaving significant lifecycle gaps.
WRITE: add a comment (note) to a company, individual, contact, opportunity or document. Visible to the Sellsy staff, not sent to the customer. Needs comments.write.
| Name | Required | Description | Default |
|---|---|---|---|
| related_id | Yes | Id of that record. | |
| description | Yes | The comment text. | |
| related_type | Yes | What it is attached to. | |
| mentioned_staff_ids | No | Staff to notify. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the mutation profile (readOnly=false, destructive=false, idempotent=false), so the description is not carrying the safety burden alone. It still adds real context beyond them: the comment is internal-only and never sent to the customer, and the call requires the comments.write scope. It omits that non-idempotency means repeat calls produce duplicate notes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, zero filler. The mutation marker comes first, then scope, then audience, then the permission requirement — front-loaded and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-param write tool with no output schema, the description covers the mutation nature, audience, and required permission, which is most of what an agent needs. It leaves out duplicate-creation risk from the non-idempotent hint and says nothing about what the call returns (e.g. a comment id).
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 every parameter including mentioned_staff_ids ('Staff to notify') is already documented in the schema. The description adds no field-level semantics beyond loosely covering the target types with the word 'document'; 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 ('add a comment (note)') and enumerates the record kinds it attaches to. The leading 'WRITE:' marker distinguishes it from the sibling read tool sellsy_search_comments, though it never names that 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?
The 'WRITE:' prefix and the target list imply when to reach for this tool rather than a read or create-entity tool, but there is no explicit when-to-use/when-not guidance and no mention of sellsy_search_comments as the read-side alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: create a company record in Sellsy (a prospect, client or supplier). Needs companies.write. Nothing is sent to the company.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Company name. | |
| note | No | ||
| type | Yes | Relationship type. | |
| No | |||
| website | No | ||
| owner_id | No | Staff id of the owner. | |
| reference | No | Your own reference. | |
| phone_number | No | ||
| mobile_number | No | ||
| number_of_employees | No | ||
| main_activity_description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description is extremely thin. It only mentions the required access scope ('companies.write') and a side effect ('Nothing is sent to the company'), which is not particularly helpful or informative behavior 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?
The description is brief and to the point. While short, it packs in the necessary scope (WRITE) and the context (Sellsy), making it efficient.
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?
Given the high parameter count (11) and low coverage (36%), the definition is incomplete. A mutation tool of this complexity requires more guidance on optional fields, acceptable data constraints, or the structure of 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 only 36%. The description fails to add any meaningful meaning or context to the 11 parameters, thus offering minimal value beyond the structure already provided in 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 description clearly identifies the action (create a company record) and the domain (Sellsy), which is specific enough. It distinguishes this from search/list tools by using the verb 'create'.
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 provides no guidance on when to use this tool versus other creation methods or how it handles missing data. It only mentions the required parameters implicitly via the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: create a contact (a person) in Sellsy. It is not linked to a company by this call. Needs contacts.write.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| No | |||
| civility | No | ||
| owner_id | No | Staff id of the owner. | |
| position | No | Job title. | |
| last_name | Yes | Last name. | |
| first_name | No | ||
| phone_number | No | ||
| mobile_number | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true). The description adds genuine context beyond that: the required permission scope ('Needs contacts.write') and the side-effect boundary that no company link is created.
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 WRITE marker and the entity identity. Every clause carries information; nothing is redundant 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?
For a 9-parameter creation tool with no output schema and thin schema coverage, the definition is minimally viable: it establishes the write nature and permission, but omits what the call returns (e.g. the new contact id) and how to subsequently associate the contact with a company.
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?
With 9 parameters and only 33% schema description coverage, the description carries a real compensation burden but mentions no parameters at all — not even which fields drive duplicate matching (e.g. email) or what civility/owner_id mean. The undocumented fields remain opaque from both sources.
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 contact (a person) in Sellsy') and clarifies the object type, which helps separate it from sellsy_create_company. It does not explicitly differentiate from sellsy_create_individual, the closest ambiguous sibling, leaving the agent to infer that distinction.
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 is not linked to a company by this call' implies a usage context (standalone person record), but the description never states when to pick this over sellsy_create_individual or sellsy_create_company, nor what call to make to attach a company afterwards.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: create an individual (a private person as prospect, client or supplier) in Sellsy. Needs individuals.write.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| type | Yes | Relationship type. | |
| No | |||
| website | No | ||
| civility | No | ||
| owner_id | No | Staff id of the owner. | |
| last_name | Yes | Last name. | |
| reference | No | ||
| first_name | No | ||
| phone_number | No | ||
| mobile_number | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a non-read-only, non-destructive, non-idempotent, open-world write, and the description usefully adds the required permission scope ("individuals.write"), which the annotations do not convey. It stops short of covering duplicate handling, failure modes, or 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?
Two terse, front-loaded clauses: the operation, then the permission requirement. Nothing is padded, though the brevity comes at the cost of the parameter and return-value coverage noted elsewhere.
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 11-parameter mutation with no output schema and low schema coverage, the description should at least say what a successful call returns or how required fields drive the payload. As written it is not sufficient for an agent to call the tool confidently without reading the schema closely.
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?
With 11 parameters and only 27% schema description coverage, the description carries a heavy burden and does almost nothing: the mention of "prospect, client or supplier" merely restates the type enum the schema already documents. It never identifies the two required fields (last_name, type) or clarifies the other nine optional parameters.
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 an individual") and defines the entity as "a private person as prospect, client or supplier," which implicitly separates it from sellsy_create_company. It does not explicitly distinguish it from sellsy_create_contact, which remains a plausible confusion point.
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 parenthetical definition implies the usage context (private person rather than a company), but there is no explicit when-to-use/when-not guidance or named alternative among the many create_* siblings. The only explicit constraint is the "individuals.write" permission requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: create a sales opportunity linked to a company, individual or contact. Needs a pipeline id and one of its step ids (see sellsy_list_opportunity_pipelines and sellsy_list_pipeline_steps). Needs opportunities.write.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Opportunity name. | |
| note | No | ||
| step | Yes | Step id inside that pipeline. | |
| amount | No | Potential amount as a decimal string, e.g. "1500.00" (account currency). | |
| related | Yes | Who it is for: one company or one individual (required), plus optional contacts. | |
| due_date | No | Due date YYYY-MM-DD. | |
| owner_id | No | Staff id of the owner (default: the API client's staff). | |
| pipeline | Yes | Pipeline id. | |
| contact_ids | No | ||
| probability | No | ||
| assigned_staff_ids | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a non-read-only, non-idempotent, non-destructive open-world write. The description adds what annotations cannot: the required 'opportunities.write' scope and the pipeline/step dependency chain that must be resolved first. It does not mention duplicate handling or failure behavior, keeping it out of the top band.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with the write classification and core requirement front-loaded, then the lookup pointers, then the permission. No filler or repetition of schema content.
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 11-parameter write tool with no output schema, the description covers the non-obvious essentials: the two required lookup ids, the related-record requirement, and the auth scope. It omits return-value expectations and optional-field guidance, but those gaps are moderate given the schema's 64% coverage.
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 64%, so the description must carry some weight, and it does: it establishes the cross-field constraint that the step id must belong to the given pipeline, which the schema lists as independent integers. It does not cover the optional fields (amount, probability, owner_id, assigned_staff_ids), but those are described adequately in 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 ('WRITE: create a sales opportunity') plus its linking scope ('linked to a company, individual or contact'), which cleanly distinguishes it from sibling create_* tools that target other resources. An agent can tell immediately what this tool produces.
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 names the prerequisite lookups ('see sellsy_list_opportunity_pipelines and sellsy_list_pipeline_steps') and the required permission scope, so the agent knows the setup path before calling. It stops short of stating when not to use it (e.g., to update an existing opportunity, use the update counterpart), so it is clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: create a task, optionally attached to a record and assigned to staff. Needs a label id (see sellsy_list_task_labels) and a due date-time. Needs tasks.write.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | ||
| due_date | Yes | Due date and time, ISO 8601 with offset, e.g. 2026-11-03T09:00:00+01:00. | |
| label_id | Yes | Task label id. | |
| owner_id | No | Staff id of the owner. | |
| priority | No | Priority level, 0 or 1. | |
| is_private | No | ||
| related_id | No | Id of that record. | |
| description | No | ||
| related_type | No | Record the task is about (give related_id too). | |
| assigned_staff_ids | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, and openWorldHint=true; the description adds the concrete auth/permission requirement ('tasks.write') and the mandatory-field dependency, which is real value beyond the structured data. It doesn't cover duplication/retry behavior even though idempotentHint=false flags that as a risk.
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: operation mode first, then prerequisites, then permission. Zero filler and nothing buried at the end.
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?
Covers the create-a-task workflow end to end for a 10-parameter, no-output-schema tool: what's required, where to get the label id, and what permission gates it. Only the return value (presumably the new task id) and defaults for optional fields are unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
At 60% schema coverage with 10 parameters, the description touches only the required pair (label_id, due_date) and the record-attachment concept. It says nothing about priority, is_private, title, or the distinction between owner_id and assigned_staff_ids, so an agent must read the schema for the majority of the surface.
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 task') plus the two scoping dimensions that matter (record attachment, staff assignment). The 'WRITE:' prefix instantly separates it from the read-oriented task siblings (get_task, list_tasks, search_tasks).
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 prerequisite lookup path explicitly ('see sellsy_list_task_labels' for a label id) and states the required scope ('Needs tasks.write'), which tells an agent what it must have before calling. No explicit when-not conditions, but for a create tool the alternatives are obvious from the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one company by id. Needs companies.read.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Company id. | |
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description usefully adds the required scope ('Needs companies.read.'), which is real auth context, but says nothing about behavior when the id is unknown or about scopes needed by embedded relations.
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 waste, purpose front-loaded before the permission requirement. Nothing to trim.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-record read with full schema documentation and rich annotations, nothing critical is missing. A brief note on not-found behavior would make it 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?
Schema description coverage is 100%, including detailed notes on embed scopes and field projection, so baseline 3 applies. The description adds no parameter meaning beyond naming the id in prose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get one company by id'), which clearly separates it from the list_/search_ siblings by scope. It does not name an alternative explicitly, so it lands at 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?
'by id' implies the tool is for direct lookups when an identifier is known, which implicitly routes agents away from sellsy_search_companies / sellsy_list_companies. However, no explicit when-to-use or when-not-to-use guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one contact by id. Needs contacts.read.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Contact id. | |
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds the permission requirement ("Needs contacts.read"), which is real value beyond the structured data, but says nothing about not-found/error behavior or that embeds may silently return null without extra scopes (only the schema hints at this).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the primary action and its identifier requirement front-loaded ahead of the permission note. Nothing is padded or repeated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter read tool with no output schema, the description covers what it does and what auth it needs. It omits the shape of the returned contact, behavior on an unknown id, and the fact that requesting embeds can yield nulls — gaps the schema only partially mitigates.
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 the schema itself documents all three parameters including embed scope caveats and field projection examples, so the baseline of 3 applies. The description adds nothing beyond "by id", contributing no semantics the schema lacks.
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?
"Get one contact by id" gives a specific verb (get), resource (contact), and scope (single, by id), which cleanly separates it from sellsy_list_contacts and sellsy_search_contacts. It stops short of naming those siblings explicitly, so differentiation is inferred from the singular/by-id framing 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 phrase "by id" implicitly tells the agent to use this when a contact id is already known, and the sibling set (list_contacts, search_contacts) makes the alternative paths guessable. However, no explicit when-to-use/when-not or named alternative is provided, leaving routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one credit note by id. Needs credit-notes.read.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Credit note id. | |
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds one genuinely useful fact beyond that — the required scope 'credit-notes.read' — but says nothing about behavior on a missing/invalid id or about errors from embed scopes.
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, zero waste, with the core action front-loaded and the auth requirement trailing as a short constraint. Nothing is padded or repeated from 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 simple single-record read with rich annotations and fully documented parameters, this covers the essentials, including the required scope. Only the behavior on a nonexistent id or an unauthorized embed is left unstated, a minor gap for a lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with the id, embed and field parameters each documented with examples and constraints, so the schema carries the burden. The description adds nothing about parameters beyond what the schema already states; 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 ('Get one credit note by id'), and 'one ... by id' implicitly separates it from the sibling list_credit_notes. It does not name the sibling explicitly, so an agent must infer the single-vs-list distinction from the name pattern.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by id' implies retrieval of a known record rather than browsing, which points away from list_credit_notes, but no when-to-use or when-not guidance is stated. Alternatives such as sellsy_list_credit_notes are never mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one estimate by id, with its rows and amounts. Needs estimates.read.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Estimate id. | |
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint and destructiveHint:false, so the safety profile is covered. The description adds the required scope, which is genuinely useful. It doesn't mention cost or size behaviour of the embed/field options, but the schema's parameter descriptions carry the extra-scope caveat.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and scope, then the required permission. 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?
Covers the core identity (single estimate by id), what is returned in broad terms (rows and amounts) and the required scope. The main gap is the absence of explicit guidance on pagination or how embed/field options affect the response, though the schema partially compensates.
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 the schema documents id, embed and field with examples, so the description need not repeat them. The description adds nothing beyond what's in the schema, which is appropriate here but not above 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 and resource ('Get one estimate by id') and scope ('with its rows and amounts'), which distinguishes it from the neighbouring list_estimates and search_estimates tools. It does not name those siblings explicitly, so sibling differentiation is only implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'by id' implies it is the tool for fetching a known estimate rather than searching, and 'Needs estimates.read' gives a prerequisite. However, there is no explicit statement of when to prefer this over sellsy_search_estimates or sellsy_list_estimates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one individual by id. Needs individuals.read.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Individual id. | |
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is fully covered by structured data. The description adds the concrete prerequisite scope 'individuals.read', which is real value not encoded in annotations, but says nothing about not-found behavior, error shapes, or whether embeds fail silently without extra scopes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the action and the id requirement front-loaded before the permission note. Nothing needs trimming.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-record read with full schema coverage, no output schema, and complete annotations, the description is minimally sufficient. It leaves out not-found handling and any hint about the returned object shape, which an agent would want before calling.
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 the embed parameter's extra-scope caveat and the field projection guidance are already documented in the schema. The description adds nothing about id validity, embed limitations, or field-selection trade-offs, so it stays at the 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 and resource ('Get one individual by id'), making the single-record intent unmistakable versus the list/search siblings. It does not name those siblings explicitly, but the singular/plural distinction carries most of the differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to prefer this over sellsy_search_individuals or sellsy_list_individuals, nor what to do if the id is unknown or the record does not exist. The only conditional information given is the required scope, which is an authorization fact rather than a usage rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one invoice by id, with its rows, amounts and status. Needs invoices.read.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Invoice id. | |
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description contributes the required scope, which is genuine added context, but says nothing about behavior on a missing/invalid id or about partial results when embed scopes are absent.
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 tight sentences with zero filler: the operation and return shape come first, then the required scope. 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?
For a simple single-record read with full annotation coverage and a fully documented schema, this is close to sufficient; it even summarizes the return payload despite there being no output schema. The remaining gap is that it does not help the agent find an id when one is unknown.
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 parameter semantics baseline is 3. The only parameter mentioned in the description is id ('by id'); embed and field, including the caveat that embed targets are null without extra scope, are handled entirely by 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 ('Get one invoice by id') and enumerates the payload it returns ('its rows, amounts and status'). The 'by id' / 'one' framing implicitly distinguishes it from sellsy_list_invoices and sellsy_search_invoices, though it never names them 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?
Adds a real prerequisite ('Needs invoices.read') that tells the agent an auth scope is required before calling. However, it gives no guidance on when to prefer this over the sibling lookup tools (search_invoices, list_invoices) when the id is unknown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one catalog item by id. Needs items.read.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Item id. | |
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds one genuinely new fact beyond them — the required items.read scope — but says nothing about what happens on a missing id (404 vs empty) or how embed scopes affect the reply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero filler; the operation is front-loaded and the auth prerequisite follows. Every sentence carries usable 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 simple read-only single-record fetch with a fully described schema and no output schema, the description covers the essentials plus the required scope. The only gap is failure behavior on an unknown id, which is minor for this tool class.
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%: id, embed (with extra-scope caveat and examples) and field (with projection examples) are all documented in the schema. The description adds no parameter meaning, 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?
"Get one catalog item by id" names a specific verb and resource and scopes it to a single record, which implicitly separates it from sellsy_list_items and sellsy_search_items. It stops short of naming those siblings explicitly, so an agent must infer the routing.
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 "by id" phrasing implies you already know the item id, which weakly signals when to prefer this over a list/search tool. No explicit when-not guidance or named alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one opportunity by id. Needs opportunities.read.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Opportunity id. | |
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely new operational context by stating the required scope 'opportunities.read', an auth prerequisite not present in the structured fields. It omits not-found/error behavior, which keeps it from 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?
Two short sentences, zero filler, with the core action and the auth requirement front-loaded. Nothing could be removed without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only single-record getter with a fully documented schema and annotations covering the safety profile, this is close to sufficient. A brief note on what is returned by default (and that 'field' can shrink the payload) would close the last gap, since no output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema itself documents embed and field with examples and constraints, so the baseline of 3 applies. The description adds nothing about parameter usage, though little is needed here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Get one opportunity by id'), and the singular 'one' distinguishes it from list_opportunities and search_opportunities. It stops short of naming those siblings explicitly, so the 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?
'By id' implies you already know the identifier, which hints at when this is appropriate rather than searching. However, no alternative is named (search_opportunities, list_opportunities) and there is no guidance on what to do when the id is unknown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one order by id. Needs orders.read.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Order id. | |
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds the orders.read scope requirement (useful auth context), but says nothing about not-found behavior or that embed targets silently null out without extra scopes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and followed by the permission requirement; nothing is wasted. It is arguably terse rather than optimally sized, since the optional parameters go unmentioned.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple by-id read with full schema coverage and complete annotations, the description is close to sufficient. Gaps: no statement of error behavior on an unknown id and no mention of the embed-triggers-extra-scope caveat that a caller may need to interpret the schema note 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 description coverage is 100%, so id, embed and field are already fully documented with examples and constraints. The description contributes nothing about the optional embed/field parameters, so the baseline of 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 ("Get one order by id"), which cleanly separates it from list_orders and search_orders siblings by scope. It does not explicitly name those alternatives, so it stops short of full sibling differentiation.
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?
"Needs orders.read" gives the required permission, which is genuine usage context. However, it never says when to prefer this over sellsy_search_orders or sellsy_list_orders, nor what happens with a bad or missing id, leaving selection guidance implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one task by id. Needs tasks.read.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Task id. | |
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile comes for free. The description's one addition is the required scope (tasks.read), which is useful but thin; it says nothing about what is returned or how embedded objects behave.
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 front-loaded ahead of the permission note.
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-record read with a fully documented schema there is little left to cover, and the scope requirement is stated. With no output schema, a hint about the returned task shape would close the last 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%, including the non-obvious embed and field parameters and their scope caveat, so the schema carries the load. The description adds nothing about id semantics beyond echoing 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: "Get one task by id." That implicitly distinguishes it from sellsy_list_tasks and sellsy_search_tasks, though neither alternative is 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?
"Needs tasks.read" gives a usable precondition for invoking the tool. It does not say when to prefer it over list_tasks or search_tasks, so selection guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List companies (customers, prospects, suppliers) with paging. Needs companies.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: name, id, created_at, updated_at. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the auth prerequisite ("Needs companies.read"), which is genuinely useful context not in annotations, but says nothing about pagination semantics or the shape of results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero waste, with the resource and entity scope front-loaded before the paging and permission notes.
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?
Adequate for a 6-optional-param read tool: schema covers all parameters and annotations cover safety. However, with no output schema, an agent gets no sense of what a page contains or how it relates to the search-based sibling, leaving routing and result expectations to inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and every parameter (embed, field, limit, order, offset, direction) is documented in-schema, including the somewhat tricky offset cursor protocol. The description adds no parameter 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 ("List companies") and clarifies scope by naming the entity types covered (customers, prospects, suppliers). It does not differentiate from the obvious sibling sellsy_search_companies or sellsy_get_company, so an agent must infer which to pick.
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?
Mentions paging and the required scope, but gives no guidance on when to use this versus sellsy_search_companies, sellsy_list_individuals, or sellsy_get_company. Usage is only implied by the verb "List".
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the contacts linked to one company (GET /companies/{id}/contacts). Needs companies.read and contacts.read.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Records per page, 1-100 (default 25). | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| company_id | Yes | Company id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent and non-destructive behavior, so the bar is lower. The description adds genuinely new context by naming the required scopes ('companies.read and contacts.read') and the underlying endpoint, which an agent cannot get from the annotations or 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 compact sentence with the resource and scope front-loaded, followed by the permission requirements. No filler. It could drop the raw endpoint path without losing meaning, which keeps it from 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 simple read-only list tool with no output schema and fully documented parameters, the description covers purpose, scope and permissions. The main remaining gap is return shape and pagination behavior, which the schema partly handles for offset but not for 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 coverage is 100% and the offset parameter is documented in unusual depth in the schema itself, including how to feed the cursor back. The description adds nothing beyond what the schema provides, 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 ('List the contacts') plus a clear scope ('linked to one company'), which implicitly distinguishes it from sellsy_list_contacts and sellsy_search_contacts. No sibling is named explicitly, so it is clear but stops short of full differentiation.
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 scope 'linked to one company' implies when this tool is appropriate versus listing all contacts or searching, but the description never states the condition explicitly or names an alternative. Usage must be inferred from the scope phrase.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List contacts (people at companies) with paging. Needs contacts.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: id, name, created_at. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the read-only, idempotent, non-destructive, open-world profile. The description adds a useful auth scope requirement and mentions paging, but it does not add deeper behavioral context beyond what annotations and schema provide.
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 two short sentences with no wasted text, and the key resource clarification is front-loaded. It is concise, though arguably too terse to be maximally helpful.
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?
Given six optional parameters and a fully documented schema, the description is adequate for basic invocation. However, for a list tool with search and company-contact siblings, it should at least signal when this is the right listing operation rather than another.
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 parameters are already well documented, including pagination, field selection, embedding, sorting, and limits. The description adds only "with paging" and no additional 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 description states a specific verb and resource ("List contacts") and clarifies that contacts are people at companies. It does not distinguish this from close siblings such as sellsy_search_contacts or sellsy_list_company_contacts, so it falls short of full purpose clarity.
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 only usage guidance is the prerequisite "Needs contacts.read." It does not say when to use this list operation instead of sellsy_search_contacts, sellsy_list_company_contacts, or sellsy_get_contact, nor does it describe exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List credit notes with paging. Needs credit-notes.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: id, number, created, date, amount. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the required scope ('credit-notes.read'), which is genuinely useful context not in the structured fields, but says nothing about pagination mechanics, rate limits, or result shape beyond noting paging exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the operation and immediately followed by the hard prerequisite. 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?
With rich annotations, full schema coverage and no output schema requirement, an agent has what it needs to call this correctly. The remaining gap is routing: nothing tells the agent this is the unfiltered lister versus the search-based siblings.
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 all six optional parameters (embed, field, limit, order, offset, direction) are documented in detail, including the cursor semantics of offset. The description adds nothing beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource ('List credit notes') with an added capability note ('with paging'), which distinguishes it from the singular sibling sellsy_get_credit_note. It does not, however, differentiate itself from sellsy_search or the other list_* tools 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?
'Needs credit-notes.read' is an auth prerequisite, not usage guidance. There is no statement of when to choose this over sellsy_search or sellsy_get_credit_note, nor any when-not condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List estimates (quotes) with paging. Needs estimates.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: id, numero, created, date, expiry_date, number, amount. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds one genuinely useful behavioral fact — the required 'estimates.read' scope — plus that results are paged, but says nothing about result count limits, default page size trade-offs, or what happens on expired cursors beyond what the schema states.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, the core action and the access requirement front-loaded ahead of any secondary detail. 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 six-parameter read-only list tool with full schema coverage and a precondition stated, the description is nearly sufficient. The remaining gap is the missing routing versus the search_estimates sibling, which matters given the sibling set.
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%, including detailed guidance on the offset cursor and embed/field semantics, so the schema carries the parameter burden. The description only echoes paging and adds no parameter meaning beyond it; 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 estimates') and disambiguates the domain term by adding '(quotes)', plus a paging note. It does not differentiate from the closely related siblings sellsy_search_estimates and sellsy_get_estimate.
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?
'Needs estimates.read' gives a clear prerequisite scope, but there is no guidance on when to call this instead of sellsy_search_estimates or sellsy_get_estimate, and no mention of supported filtering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List individuals (private customers, prospects, suppliers) with paging. Needs individuals.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: name, id, created_at, updated_at. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the required OAuth scope, which is genuinely non-redundant. It says nothing about default ordering, page size behavior, or what happens with embeds lacking scopes — though the schema covers embeds well.
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 clauses, no filler, entity clarification and permission requirement both front-loaded. Nothing could be removed without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A read-only list tool with zero required parameters, full schema coverage and complete annotations needs comparatively little prose. The one meaningful gap is sibling routing versus sellsy_search_individuals, which an agent must otherwise guess.
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 parameter (embed, field, limit, order, offset, direction) is documented in-schema, including the tricky dual-type offset cursor. The description adds only 'with paging', which conveys nothing beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List individuals') and disambiguates the entity by naming what individuals are (private customers, prospects, suppliers), which is valuable in a CRM where 'contact' and 'individual' are distinct siblings. It does not, however, distinguish itself from sellsy_search_individuals or sellsy_get_individual.
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?
'Needs individuals.read' gives the access prerequisite, and 'with paging' implies the bulk-enumeration use case. There is no explicit statement of when to prefer this over sellsy_search_individuals for filtered retrieval, leaving the choice to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the payments linked to one invoice. Needs invoices.read and payments.read.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Records per page, 1-100 (default 25). | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| invoice_id | Yes | Invoice id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's main contribution is disclosing the required OAuth scopes invoices.read and payments.read — genuinely useful auth context an agent cannot get from annotations. Paging behavior is left to the schema, which handles it thoroughly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the resource and scope front-loaded before the permission requirement. 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?
A simple read-only list tool with full annotation coverage, a fully documented 3-parameter schema, and no output schema to explain. Adding a pointer to the alternative payment-search tool would make it complete, but nothing required for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so invoice_id, limit, and offset are already documented, including the non-trivial dual-mode offset contract. The description adds only the notion that invoice_id selects the parent invoice; baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (List) and resource (payments) with a clear scope qualifier: payments linked to ONE invoice. This is enough to distinguish it from the collection-wide sibling sellsy_search_payments, though it never names that 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?
The scoping phrase implies when to use it (per-invoice payment lookup), but there is no explicit when-not guidance or pointer to sellsy_search_payments for cross-invoice queries. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List invoices with paging. Needs invoices.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: id, number, created, date, amount, due_date. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description adds a genuinely non-structured detail: the required OAuth scope 'invoices.read', plus the fact that results are paged — value 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?
Two short sentences, no filler, with the core action front-loaded ahead of the permission requirement. 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?
All six parameters are optional and fully documented in the schema, and there is no output schema, so the description need only cover scope and intent. It does that, though it omits any hint of the response/pagination contract or the sibling distinction, 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%, including detailed offset/cursor paging semantics, embed scopes and field projection, so the schema does the heavy lifting. The description's 'with paging' only gestures at what the offset/limit params already document thoroughly, 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?
States a specific verb and resource ('List invoices with paging'), which is immediately clear. However, it does not distinguish itself from the sibling sellsy_search_invoices or sellsy_get_invoice, leaving the agent to infer the difference between a plain list and a filtered search.
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 only guidance is the prerequisite 'Needs invoices.read', which is useful auth context but not a usage rule. It never says when to prefer this over sellsy_search_invoices or when paginating vs fetching a single invoice via sellsy_get_invoice, so the selection logic is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List catalog items (products, services, shipping, packaging) with paging. Needs items.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: id, created_at. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered without the description. The description adds value by naming the required OAuth scope ('items.read'), which annotations do not convey. It omits detail on pagination semantics, but the schema carries that fully.
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 sentence, front-loaded with the verb and resource, followed by the scope requirement. Every clause carries information; nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-required-param, read-only list tool with a fully documented schema and rich annotations, the description covers purpose, subject matter and the auth scope. The only remaining gap is routing guidance versus the search/get siblings, which is a selection issue rather than a missing invocation 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 description coverage is 100% and the paging cursor, embed, field and limit parameters are documented in detail in the schema itself. The description's only contribution is 'with paging', which adds no syntax or behavior beyond what the schema states, 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 (List) and resource (catalog items), and goes further by enumerating the item subtypes (products, services, shipping, packaging), which an agent cannot infer from the name alone. It does not distinguish itself from the sibling sellsy_search_items or sellsy_get_item, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The prerequisite 'Needs items.read' is a useful gating condition for invocation, and the description implies bulk retrieval. However, there is no explicit guidance on when to pick this over sellsy_search_items (filtered lookup) or sellsy_get_item (single record), leaving the agent to infer the choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List sales opportunities with paging. Needs opportunities.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: id, created, step_rank, due_date, amount. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description usefully adds the required permission scope ('Needs opportunities.read'), but says nothing about default page size behavior, result caps, or what a page 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?
Two short sentences, front-loaded with purpose followed by the prerequisite. Nothing is wasted, though the second sentence is terse to the point of being cryptic about the exact scope string format.
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 tool with no output schema, the definition covers the essential permission prerequisite and acknowledges paging, which is the minimum an agent needs. It leaves the relationship to the search sibling and the shape of returned pages unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains embed, field, limit, order, offset, and direction in detail. The description only alludes to 'paging' generically and adds no syntax or defaults beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List sales opportunities') plus the paging behavior, which clearly separates it from get_ and create_ siblings. It does not explicitly distinguish itself from sellsy_search_opportunities, which reads as a very similar operation.
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 mention of paging and the required scope gives implied usage context, but there is no statement of when to prefer this over sellsy_search_opportunities or how to switch between them. The agent must infer the choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the sales pipelines (needed to create an opportunity: pipeline id and step id). Needs opportunities.read.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Records per page, 1-100 (default 25). | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds real value beyond that by disclosing the authorization requirement ('Needs opportunities.read'), which an agent cannot infer from annotations or 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?
Two clauses, zero filler, with the motivating use case parenthetically front-loaded. Every phrase — the resource, the dependent ids, the scope — 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 small read-only list tool with fully documented parameters and no output schema, this is nearly complete: it tells the agent what it returns conceptually (pipelines with pipeline/step ids) and what it is needed for. A brief note on the returned fields or the step-related sibling would make it 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?
Schema description coverage is 100%, and the limit/offset descriptions already explain paging semantics in detail. The description adds nothing about parameters, so the baseline of 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 ('List the sales pipelines') and immediately frames the purpose (gathering pipeline id and step id for opportunity creation). It does not explicitly distinguish itself from the sibling sellsy_list_pipeline_steps, which is the natural point of confusion, so it falls just short of 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?
Gives a clear use case — call this before sellsy_create_opportunity because you need pipeline and step ids — plus the required scope 'opportunities.read'. It stops short of naming the related sibling (sellsy_list_pipeline_steps) or stating exclusions, so it is clear context without full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List orders with paging. Needs orders.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: id, number, created, date, amount, due_date, order_status. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so the safety profile is covered. The description adds one genuinely useful piece beyond them: the required orders.read scope. It says nothing about rate limits, maximum result windows, or how paging behaves when records change between calls.
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 resource and the paging trait, then the permission requirement. Nothing is padded, though the phrasing is so terse that it borders on under-specification rather than crispness.
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 could have said something about the response envelope or how a paginated batch is shaped. The schema compensates heavily on parameters, and annotations cover safety, so what remains is a modest but real gap for a list-and-page 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 every parameter including offset, limit, order, direction, embed and field documented in more detail than the description could carry. The description's only contribution is the word "paging", which the schema's offset description already explains fully. 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 orders") plus a behavioral qualifier ("with paging"), which separates it in spirit from sellsy_get_order and sellsy_search_orders. It stops short of explicitly naming those siblings, so an agent still has to infer the list-vs-get-vs-search boundary.
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?
"with paging" implies browsing a result set rather than fetching a single known order, and "Needs orders.read" states a prerequisite. There is no explicit statement of when to prefer this over sellsy_search_orders, which is the most plausible alternative for this resource.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the steps of one opportunity pipeline. Needs opportunities.read.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Records per page, 1-100 (default 25). | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| pipeline_id | Yes | Pipeline id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds the permission scope requirement, which is genuinely useful and not in the structured data, but says nothing about result volume, pagination behavior, or ordering of returned steps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero filler, with the core action stated first and the permission requirement second. Nothing could be removed without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, single-required-parameter listing tool with full schema coverage and no output schema, this is nearly sufficient. A brief note on what a pipeline step contains or how to obtain a pipeline_id from the sibling lister would close 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%: limit, offset (including the string-vs-numeric cursor rule) and pipeline_id are all documented in the schema. The description adds no meaning beyond that, which is the correct baseline of 3 when the schema does the work.
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 gives a specific verb (List) and resource (steps of one opportunity pipeline), and the words 'one' / 'steps' distinguish it conceptually from sellsy_list_opportunity_pipelines. It stops short of naming that sibling, so the agent must infer the boundary 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?
'Needs opportunities.read' supplies a concrete prerequisite, which is real usage guidance. However, there is no explicit when-to-use statement, no exclusion, and no pointer to sellsy_list_opportunity_pipelines for discovering pipeline ids, so routing is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the staff members of the account (the list may hold only yourself, depending on the Sellsy plan). Needs staffs.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: id, name. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds behavior not in annotations: the required OAuth scope and the fact that the result set can be truncated by plan tier — a real interpretation risk an agent should know about.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no wasted words; the permission requirement is front-loaded in the second sentence and the plan caveat follows immediately. Nothing repeated from the title or annotations.
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, zero-required-parameter list tool with fully documented schema and no output schema, the description covers purpose, permission, and the plan constraint. It does not mention pagination or result shape, but the schema handles paging and annotations handle safety, so this is close to 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% and the six parameters (embed, field, limit, order, offset, direction) are each documented in the schema, including cursor pagination semantics. The description adds nothing about parameters, which is acceptable at baseline 3 but leaves no added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("List the staff members of the account") with a clear scope qualifier about plan-dependent results. No sibling exposes staff data, so differentiation is implicit rather than stated, which keeps it short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description supplies a prerequisite ("Needs staffs.read") and a caveat that the list may only contain yourself depending on plan, which helps an agent interpret empty/limited results. It gives no guidance on when to use this versus other listing/search tools or what to do when results look sparse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the task labels (a label id is required to create a task). Needs tasks.read.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Records per page, 1-100 (default 25). | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent and non-destructive behavior, so the description only needs to add context. It does contribute the required permission scope ("Needs tasks.read"), which is genuine added value, but says nothing about result shape or pagination behavior beyond what the schema documents.
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 clauses, front-loaded with the action and resource, then the usage rationale. No filler and no repetition of schema or annotation content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read tool with no output schema, the description covers purpose, the triggering context, and the auth requirement. A brief note on what a label contains would close the remaining gap, but an agent has enough to call it 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 description coverage is 100% and both limit and offset are thoroughly documented there, including the string-vs-numeric cursor rule. The description adds nothing about parameters, which meets the baseline but no more.
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 task labels") and adds a parenthetical explaining what labels are for, which separates it from sellsy_list_tasks. It does not explicitly name the sibling it differs from, but the resource is distinct enough that confusion is unlikely.
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 parenthetical "a label id is required to create a task" tells the agent exactly when to reach for this tool — before sellsy_create_task. It stops short of naming alternatives or exclusions, but the usage trigger is concrete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tasks with paging. Needs tasks.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: id, due_date. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered structurally. The description adds the required scope (tasks.read), which is real value beyond annotations, and mentions paging. It says nothing about the paging cursor semantics or that embed fields may silently return null without extra scopes — though the schema covers those.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the operation and scope, then the permission requirement. Nothing is repeated and every clause adds something the schema or annotations do not.
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 six optional, fully documented parameters and rich annotations, the description is sufficient to call the tool correctly, but it omits the one context an agent actually needs: how this differs from sellsy_search_tasks in the same namespace. Adequate but with a clear 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%, including detailed cursor semantics for offset and the 1-100/default-25 limit, so the schema carries the parameter burden. The description only echoes 'with paging' and adds no parameter guidance beyond that. 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 tasks') plus a scope note ('with paging'), so the agent knows this is a paginated enumeration of tasks. It does not contrast itself with the sibling sellsy_search_tasks, which is the nearest competing read operation, so sibling differentiation is missing.
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 prerequisite 'Needs tasks.read' is genuinely useful context for invocation (auth scope). However, there is no guidance on when to use this versus sellsy_search_tasks or sellsy_list_task_labels, and no note about filtering capability or lack thereof. Usage is only implied by the verb 'List'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free-text search over companies, individuals, contacts, opportunities, items, documents and staff in one call (GET /search). Use it to find a record by name, email or number when you do not know its type. Needs the search.read scope.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | The text to search for. | |
| type | No | Restrict to these object types or subtypes (e.g. company.client, document.invoice). Omit to search everything. | |
| limit | No | Records per page, 1-100 (default 25). | |
| archived | No | true = only archived records. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: the auth requirement ('Needs the search.read scope') and the underlying GET /search endpoint. It does not describe pagination or result ordering, and the per-page nature of 'limit' is only visible 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?
Two sentences, front-loaded with the capability, then the usage condition and the scope requirement. Zero filler and nothing repeated verbatim from 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 four-parameter read tool with rich annotations, the description covers what is searched, when to use it, and the permission needed. Since there is no output schema, a brief note on result shape or whether results are mixed-type would have completed 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 four parameters (q, type, limit, archived) are already fully documented. The description only contributes a light gloss on what q matches (name, email, number) and says nothing about combining the type array with free text. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (free-text search) plus the full set of resources it spans (companies, individuals, contacts, opportunities, items, documents, staff) and the underlying endpoint GET /search. The phrase 'in one call' and the cross-type scope distinguish it cleanly from the many type-specific siblings like sellsy_search_companies and sellsy_search_invoices.
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 says to use it 'to find a record by name, email or number when you do not know its type,' which is a clear selection condition. The alternative (typed search tools) is only implied by that condition rather than named, and there is no statement of when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search comments and notes by author, date, parent comment or the company/individual/contact they are attached to. Needs comments.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: id, updated, created. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| filters | No | Search filters as an object. Unknown keys are refused by Sellsy. Keys: owners [staff ids], companies [ids], individuals [ids], contacts [ids], parent_id, related_objects [{type,id}], created {start,end} ISO date-times, updated {start,end} ISO date-times. | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds one genuinely new fact beyond annotations – the required comments.read scope. It says nothing about result volume, pagination behavior, or that embedded relations return null without extra scopes, which are the behaviors an agent would otherwise hit blind.
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, zero filler, with the capability stated first and the access prerequisite trailing. Nothing is repeated and nothing could be cut without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter search tool with a nested filters object and no output schema, the description covers purpose and auth but leaves the agent without any indication of what comes back or how facets combine (AND vs OR). The dense schema compensates for most of the parameter side, but the absence of return-value framing is a real 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 the baseline is 3. The description restates the filter facets (author, date, parent comment, attached entity) at a conceptual level that maps onto the filters keys, but adds no syntax or constraints 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?
States a specific verb (search) and resource (comments and notes) plus the facets it can be filtered by, which clearly separates it from the generic sellsy_search and the entity-specific search tools. It doesn't explicitly name a sibling to route against, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage guidance is the prerequisite 'Needs comments.read.', which is helpful but not a when-to-use rule. There is no statement about when to prefer this over sellsy_search or over fetching a company/contact and reading its notes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search companies by name, email, type (prospect/client/supplier), reference, VAT, SIRET, country, postal code, creation or update date. Needs companies.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: name, id, created_at, updated_at. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| filters | No | Search filters as an object. Unknown keys are refused by Sellsy. Keys: name (exact), email (exact), type ("prospect"|"client"|"supplier" or an array), is_archived (bool), siret, vat, reference [..], id [ids], contacts [contact ids], country_code, postal_code [..], created {start,end} ISO date-times, updated_at {start,end} ISO date-times, number_of_employees {min,max}. | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds a concrete scope requirement ('companies.read'), which is real value beyond the annotations, but says nothing about result size, pagination, or empty-result behavior for a search across an open-world dataset.
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, zero filler, with the searchable-field list front-loaded and the permission note trailing. Nothing here is redundant 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?
For a 7-parameter tool with a nested filters object and no output schema, the description omits what a search returns and how paging/embed/field projection interact with results, leaving the schema to carry that load. The missing search-vs-list sibling routing is the most significant 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 the parameter semantics are already fully documented, including the nested filters keys, embed, field, and the offset paging rules. The description restates a subset of the filter keys and adds the type enum values, which is marginal added value; 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) plus resource (companies) and enumerates the searchable attributes, so the agent knows exactly what can be queried. However, it never distinguishes itself from the sibling sellsy_list_companies, leaving the search-vs-list choice unresolved.
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 listed filter fields imply when to reach for this tool (attribute-based lookup), and 'Needs companies.read' signals a prerequisite scope. But there is no explicit statement about when to prefer it over sellsy_list_companies or sellsy_get_company, nor any exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search contacts by last name, email, phone, linked company or individual, creation date. Needs contacts.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: id, name, created_at. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| filters | No | Search filters as an object. Unknown keys are refused by Sellsy. Keys: last_name, email, phone_number, mobile_number, companies [company ids], individuals [individual ids], id [ids], is_linked (bool), country_code, postal_code [..], created {start,end} ISO date-times, updated {start,end} ISO date-times. | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds the required OAuth scope ('contacts.read'), which is genuinely extra value, but says nothing about pagination, result caps, or matching semantics (exact vs partial) beyond what the schema documents.
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 tight sentences with the searchable scope front-loaded and the auth requirement trailing. Nothing is wasted, though the brevity leaves room to add sibling routing without bloat.
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 search with full schema and annotations, purpose and permission are covered. The remaining ambiguity—how it differs from list_contacts and from the generic search tool, and whether filters are exact-match or fuzzy—is not addressed.
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 the schema itself details filters keys, cursor paging, embed and field projection. The description's list of searchable criteria mirrors the filters description rather than adding syntax or constraints, so it earns baseline credit 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 and resource ('Search contacts') and enumerates the searchable criteria, so the agent knows exactly what can be matched. It does not distinguish itself from sellsy_list_contacts or the generic sellsy_search, which a competent agent would want to know before choosing.
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?
'Needs contacts.read' gives a useful prerequisite for calling it, and the listed criteria imply when filtering is appropriate. However, there is no explicit statement of when to prefer this over sellsy_list_contacts (unfiltered listing) or sellsy_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search estimates by status, number, date, currency, owner, contact or related company/individual/opportunity. Needs estimates.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: id, numero, created, date, expiry_date, number, amount. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| filters | No | Search filters as an object. Unknown keys are refused by Sellsy. Keys: status ["draft"|"sent"|"read"|"accepted"|"refused"|"expired"|"advanced"|"partialinvoiced"|"invoiced"|"cancelled"], number (exact), currency, date {start,end} dates YYYY-MM-DD, created {start,end} ISO date-times, updated {start,end} ISO date-times, owners [staff ids], assigned_staff_ids [..], contacts [contact ids], related_objects [{type,id}] (type company|individual|opportunity). | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, and open-world behavior. The description adds the required scope ('estimates.read'), which is valuable auth context, but it does not mention pagination behavior or that unknown filter keys are refused—details 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?
Two short sentences, front-loaded with the primary purpose and immediately followed by the required scope. Every sentence earns its place, with no redundant or filler content.
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 search tool with a fully described nested filter schema and annotations covering safety, the description supplies the essential purpose and auth requirement. It could be more complete by distinguishing this from sibling list/get/search tools, but nothing critical for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all seven parameters, including the complex nested filters object, are fully documented in the schema. The description lists the same filter categories but adds no syntax, format, or behavior beyond what the schema already provides, so 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?
The description gives a specific verb and resource ('Search estimates') and enumerates the filter dimensions, so the tool's purpose is clear. It does not explicitly distinguish itself from sibling tools like sellsy_list_estimates or sellsy_get_estimate, which keeps it from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The prerequisite 'Needs estimates.read' is useful usage context, but there is no explicit guidance on when to use this search tool versus list_estimates, get_estimate, or the generic sellsy_search. Usage is implied by the filter enumeration rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search individuals by name, email, type, reference, country, postal code, creation or update date. Needs individuals.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: name, id, created_at, updated_at. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| filters | No | Search filters as an object. Unknown keys are refused by Sellsy. Keys: name (exact), email (exact), type ("prospect"|"client"|"supplier" or an array), is_archived (bool), reference [..], id [ids], country_code, postal_code [..], created {start,end} ISO date-times, updated_at {start,end} ISO date-times. | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the required permission scope (`individuals.read`), a genuinely additive behavioral fact not present in annotations; it stops short of noting pagination behavior or empty-result handling, which the schema happens to cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, no filler: the capability statement comes first and the prerequisite trails it. 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?
With no output schema, the description could say what a result record contains or that results are paged, but it does not — pagination semantics live entirely in the `offset`/`limit` schema text. Given 7 mostly-optional params and a nested `filters` object, the description is adequate but leaves the agent to read the schema for return shape.
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 the schema docs already spell out each filter key, embed, field, limit, order, offset and direction in detail. The description's list of searchable fields partly duplicates `filters` documentation, adding only a summary, 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 (Search) and resource (individuals) and enumerates the searchable fields, so the agent knows exactly what the tool covers. It does not, however, distinguish itself from the sibling `sellsy_list_individuals` (unfiltered listing) or `sellsy_search` (global search), which an agent must infer.
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 "Search" plus the enumerated filter fields implies this is the filtered-query path, and "Needs individuals.read" states the prerequisite scope. There is no explicit when-to-use/when-not guidance, and no pointer to `list_individuals` or `get_individual` as alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search invoices by status (draft/due/payinprogress/paid/late/cancelled), number, date, currency, owner, or related company/individual/opportunity. Use it for unpaid or late invoices. Needs invoices.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: id, number, created, date, amount, due_date. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| filters | No | Search filters as an object. Unknown keys are refused by Sellsy. Keys: status ["draft"|"due"|"payinprogress"|"paid"|"late"|"cancelled"], number (exact), currency, date {start,end} dates YYYY-MM-DD, created {start,end} ISO date-times, updated {start,end} ISO date-times, owners [staff ids], assigned_staff_ids [..], contacts [contact ids], related_objects [{type,id}] (type company|individual|opportunity), is_deposit (bool), is_progress_invoice (bool). | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so safety behavior is covered. The description adds the important auth prerequisite (invoices.read), but does not add richer behavioral context such as return shape or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the search capability, and includes only useful details. Every sentence contributes either filter scope or the required permission.
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 seven-parameter search tool with nested filters and no output schema, the description names the main search axes, gives a usage scenario, and states the required scope. The schema covers pagination and detailed filter semantics, though the description does not distinguish this tool from list_invoices or describe return shape.
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 fully documents the seven parameters, including nested filters and pagination. The description summarizes some filter keys but omits others and adds little syntax or meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource and enumerates the main search dimensions, including status values and related object types. It is clear what the tool does, but it does not distinguish this search from the sibling sellsy_list_invoices or general sellsy_search.
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 explicitly says to use the tool for unpaid or late invoices and states the required invoices.read scope, which gives a clear usage context. It does not provide exclusions or name alternatives such as list_invoices for browsing all invoices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search catalog items by name, reference or type. Needs items.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: id, created_at. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| filters | No | Search filters as an object. Unknown keys are refused by Sellsy. Keys: name, reference, type ["product"|"service"|"shipping"|"packaging"], is_archived (bool). | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the required scope (items.read), which is genuinely useful and not in structured data. It says nothing about pagination behavior or result shape beyond what the schema already conveys.
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 the search scope front-loaded and the prerequisite second. No filler or 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?
Seven parameters including a free-form nested filters object and a dual-mode cursor/numeric offset, with no output schema, make this a fairly complex call. The description leaves pagination semantics and the shape of results entirely to the schema, which is rich but not self-explanatory for the offset dual-mode. Adequate but thin 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%, so the schema already documents limit, offset, order, direction, field, embed and the filter keys. The description's mention of name/reference/type loosely maps to the filters object but adds no syntax or format detail. Baseline 3 applies when the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource (search catalog items) and the fields searched (name, reference, type), which makes it distinguishable from list_items or get_item by implication. It never explicitly contrasts itself with those siblings, so it falls short of 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?
No guidance on when to use this instead of sellsy_list_items or sellsy_search. The only contextual statement is a scope prerequisite ('Needs items.read'), which is an auth condition, not a usage rule. An agent must infer that this is the filtered variant of list_items.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search opportunities by name, number, pipeline, step, status (open/won/lost/cancelled/closed/late), amount, owner or due date. Needs opportunities.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: id, created, step_rank, due_date, amount. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| filters | No | Search filters as an object. Unknown keys are refused by Sellsy. Keys: name, number, pipeline [pipeline ids], step [step ids], statuses ["open"|"won"|"lost"|"cancelled"|"closed"|"late"], amount {min,max}, owners [staff ids], assigned_staffs [staff ids], related_objects [{type:"company"|"individual",id}], created {start,end} ISO date-times, due_date {start,end} ISO date-times. | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description contributes the scope requirement (opportunities.read), which is valuable, but says nothing about result size, paging behavior, or matching semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short clauses, front-loaded with the primary search capability, with the auth prerequisite trailing. Nothing is wasted, though the enumeration largely duplicates schema content.
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, zero-required, read-only search tool with fully documented schema and rich annotations, the description plus structured fields give an agent enough to invoke it correctly. Only the absence of paging/return-shape hints (no output schema exists) keeps this below 5.
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 limit/offset/order/direction/filters/embed/field all documented in detail, including cursor-vs-numeric paging. The description only re-lists filter dimensions already present in the filters schema, adding no syntax or format 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 (opportunities) and enumerates the searchable dimensions, which makes the retrieval semantics clear. It does not, however, distinguish itself from close siblings like sellsy_list_opportunities or the generic sellsy_search, so an agent must infer the boundary.
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?
"Needs opportunities.read" gives a real prerequisite, and the enumerated filter fields imply this is the tool for filtered/query retrieval. But there is no explicit when-to-use vs. list_opportunities or generic search, and no statement about how multiple filters combine.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search orders by status or delivery status, or related company/individual/opportunity. Needs orders.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: id, number, created, date, amount, due_date, order_status. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| filters | No | Search filters as an object. Unknown keys are refused by Sellsy. Keys: status ["draft"|"sent"|"read"|"accepted"|"expired"|"advanced"|"invoiced"|"partialinvoiced"|"cancelled"], order_status ["none"|"wait"|"picking"|"sent"|"partialsent"], related_objects [{type,id}], updated {start,end} ISO date-times. | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description usefully adds the required scope (orders.read) but says nothing about result caps, pagination behavior, or the cost of embeds, which the schema only partly implies.
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 compact sentence that front-loads the searchable dimensions and appends the permission note. No padding, but it is arguably too terse for a 7-parameter tool with a nested filters object.
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 search tool with fully documented schema and no output schema, the description covers purpose, filterable fields and auth requirement. The remaining gap is pagination/return-shape expectations, which the schema's offset description largely handles.
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 every parameter (embed, field, limit, offset, filters, order, direction) is already documented in detail, including filter key enumerations. The description only restates the filter domains, adding no syntax or format 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 (search) plus resource (orders) and names the filterable dimensions (status, delivery status, related company/individual/opportunity). It is clearly distinguishable from get_order and create_* siblings, though it does not contrast itself with sellsy_list_orders.
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?
Only guidance is the permission prerequisite "Needs orders.read." There is no explicit statement of when to prefer this search tool over sellsy_list_orders or sellsy_search (the generic one), leaving the choice to inference from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search payments by status (pending/confirmed/rejected/failed/refund) or related company/individual. Needs payments.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: id, paid_date. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| filters | No | Search filters as an object. Unknown keys are refused by Sellsy. Keys: status ["pending"|"confirmed"|"rejected"|"failed"|"refund"], related_objects [{type,id}]. | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds one genuinely useful operational fact — the payments.read scope requirement — but says nothing about paging behavior or result shape beyond what the schema already documents.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler, and the searchable facets are front-loaded before the auth requirement. Efficient, though the second sentence is a bare credential note rather than structured guidance.
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 7 parameters, nested filters, and no output schema, the description should at least sketch what a result looks like (payment record fields, pagination envelope) and how it differs from list_invoice_payments. The rich schema compensates for parameter gaps, but the return-shape and sibling-routing gaps remain.
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 every parameter is already documented in detail, including status enum values and paging semantics. The description only restates the status values and the company/individual filter idea, adding no syntax or format 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 (search payments) plus the two axes it searches on (status, related company/individual), which is clear beyond the title. It does not differentiate from the sibling sellsy_list_invoice_payments, so an agent cannot tell from the description which of the two to pick.
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: it names the filters available, which hints that this is used when narrowing payments by status or counterparty. There is no explicit when/when-not guidance and no mention of the alternative sibling list tool, leaving the choice to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search tasks by status (todo/done), owner, assignee, label, due date or related record. Needs tasks.read.
| Name | Required | Description | Default |
|---|---|---|---|
| embed | No | Related objects to include (each may need an extra scope and is null without it), e.g. ["invoicing_address","main_contact","cf.1542"]. | |
| field | No | Only return these fields, e.g. ["id","name"] or ["address.id"], to keep replies small. | |
| limit | No | Records per page, 1-100 (default 25). | |
| order | No | Sort field: id, due_date. | |
| offset | No | Paging cursor. Leave out for the first page. If the previous reply's pagination.offset is a string, pass it back unchanged for the next page. Only a number sets numeric paging: then pass the previous offset plus limit (0, 25, 50, ... for limit 25) until count is below limit. | |
| filters | No | Search filters as an object. Unknown keys are refused by Sellsy. Keys: statuses ["todo"|"done"], owners [staff ids], assigned_staffs [staff ids], labels [label ids], priority {min,max} 0-1, companies [ids], individuals [ids], contacts [ids], related_objects [{type,id}], created {start,end} ISO date-times, due_date {start,end} ISO date-times. | |
| direction | No | Sort direction (default asc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive), so the description correctly adds only the permission requirement 'Needs tasks.read', which is real context not in the structured fields. It says nothing about result size, paging behavior, or whether empty results are error vs empty list — though paging is partly described 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?
Two sentences, no filler; the capability statement comes first and the permission requirement second. Nothing could be removed without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only 7-parameter search with a nested filters object and no output schema, the definition covers permission and filter scope but leaves the result shape (what a task record contains, what pagination.offset looks like) unaddressed and gives no disambiguation against list_tasks. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the filters object already enumerates statuses, owners, assigned_staffs, labels, due_date ranges, etc., and offset/limit/embed/field are fully documented there. The description's filter list merely restates a subset of the filters 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 (search) and resource (tasks) plus the filterable dimensions, so the agent knows it's a filtered task query. It does not distinguish itself from the co-existing sellsy_list_tasks or the generic sellsy_search, so an agent cannot tell from the description alone which of the three is right.
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 enumerated filter axes imply when the tool is useful (targeted task lookup by status/owner/date), and 'Needs tasks.read' flags a prerequisite. But there is no explicit when-not, and no pointer to sellsy_list_tasks for unfiltered listing or sellsy_get_task for single retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
sellsy_create_commentsellsy_create_companysellsy_create_contactsellsy_create_individualsellsy_create_opportunitysellsy_create_tasksellsy_get_companysellsy_get_contactsellsy_get_credit_notesellsy_get_estimatesellsy_get_individualsellsy_get_invoicesellsy_get_itemsellsy_get_opportunitysellsy_get_ordersellsy_get_tasksellsy_list_companiessellsy_list_company_contactssellsy_list_contactssellsy_list_credit_notessellsy_list_estimatessellsy_list_individualssellsy_list_invoice_paymentssellsy_list_invoicessellsy_list_itemssellsy_list_opportunitiessellsy_list_opportunity_pipelinessellsy_list_orderssellsy_list_pipeline_stepssellsy_list_staffssellsy_list_task_labelssellsy_list_taskssellsy_searchsellsy_search_commentssellsy_search_companiessellsy_search_contactssellsy_search_estimatessellsy_search_individualssellsy_search_invoicessellsy_search_itemssellsy_search_opportunitiessellsy_search_orderssellsy_search_paymentssellsy_search_tasksRead and write Insightly contacts, organisations, leads, opportunities, tasks and notes.
Read deals, persons, organizations, activities and pipelines; create and update CRM records.
Read CentralStationCRM people, companies, deals, tasks; create and update people, companies, deals.
Create, search, update, and manage data in OnePageCRM.
Add one secure layer between your agents and this server.
