Saldeo MCP by usefulapi

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the per-type 200-id batching constraint; it says nothing about what 'full documents' contain or how paging behaves, leaving that 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?

One compact sentence with the guidance front-loaded and the underlying endpoint appended as a trailing reference. No filler.

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

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

For an 11-parameter read-only fetch with no output schema, the description establishes the id source, the per-type grouping and the batch cap. The only gap is a hint of what the returned 'full documents' look like, which a caller must infer.

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 type array and the paging parameters are already documented. The description reinforces the 200-per-call cap and the 'per type' semantics, but adds little else 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 concrete verb and resource ('Get full documents of one company by id, per type') and names the sibling that provides the ids. The 'full documents' vs id-list contrast implicitly separates it from saldeo_list_document_ids, but it never explicitly distinguishes it from saldeo_get_invoices_by_ids.

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?

Tells the agent where the ids come from ('use the groups from saldeo_list_document_ids') and gives a hard operational limit (at most 200 ids per call). It stops short of saying when to prefer this over saldeo_get_invoices_by_ids or saldeo_search_documents.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds the 200-id cap and the underlying POST endpoint, plus that full (not partial) invoice objects come back. It says nothing about behavior for ids that don't exist or belong to another company, which is the main unknown for a batch-by-id fetch.

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, front-loaded with the verb and scope, followed by the id source and the batch cap. The trailing endpoint reference is the only arguable overhead and is short enough not to hurt.

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 read-only fetch with full schema coverage and no output schema, the description covers scope, id provenance, and batching. It could go further by sketching the returned invoice structure or confirming paging behavior of the reply, but nothing critical 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%, with per-parameter descriptions for invoices, pre_invoices, corrective variants, limit and offset, so the schema does the heavy lifting. The description only reinforces the id source and the 200-item ceiling already encoded as maxItems, adding no new parameter meaning.

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 full invoices'), the scope ('of one company'), and the id source, which separates it from the sibling saldeo_list_invoice_ids that only returns ids. It does not explicitly distinguish itself from saldeo_list_invoices, so the boundary with that sibling is left 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?

It gives a prerequisite chain ('ids from saldeo_list_invoice_ids') and a hard batching constraint ('at most 200 per call'), which is useful operational context. However, there is no statement of when to prefer this over saldeo_list_invoices or what to do when a batch exceeds 200.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds value by disclosing that each statement carries related entries, contractors and links, but says nothing about volume, paging behavior, or ordering beyond what the schema covers.

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

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

Two short sentences, front-loaded with the action and resource, followed by the endpoint reference. No filler, though the raw endpoint path is of marginal value to an agent.

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

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

For a read-only list tool with no output schema, the description tells the agent what content comes back (statements plus nested entries/contractors/links), and pagination is fully specified in the schema. Sufficient to call correctly, with only ordering/response-shape niceties 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 limit, offset and company_program_id are fully documented in the schema. The description only reinforces the company scoping ('of one company') and adds no syntax or format detail beyond the schema 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+resource ('List the bank statements of one company') and enumerates the included data (entries, contractors, links). The resource is clearly distinct from siblings like saldeo_list_invoices or saldeo_list_documents, though no sibling is named explicitly.

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

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

Usage is only implied: a required company_program_id signals that this lists statements for a single company. There is no explicit when-to-use, when-not, or pointer to an alternative tool for other bank-statement needs.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety traits are covered. The description adds useful scope behavior — companies "the Saldeo user can see" — and lists the returned fields, including the critical COMPANY_PROGRAM_ID dependency.

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

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

The description is compact and front-loaded: it leads with what is listed, then key returned fields, then "Start here," then the underlying endpoint. Every sentence carries useful routing or output 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 listing tool, the description supplies the essential output fields and the dependency signal around COMPANY_PROGRAM_ID. Pagination details are handled by the schema, and no output schema is needed given the explicit field list.

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 limit and offset parameters are already fully documented in the schema. The description does not add further parameter meaning beyond the schema 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 — list companies/clients visible to the Saldeo user — and explains the key returned identifier, COMPANY_PROGRAM_ID, which is needed by every other tool. This distinguishes it from sibling tools and makes the tool's role unmistakable.

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 "Start here" gives explicit first-step guidance, and "needed by every other tool" clarifies why an agent should call this before dependent tools. It does not name alternatives or exclusions, but there is no directly competing company-listing sibling.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the upstream endpoint reference and a summary of returned fields, but says nothing about volume, ordering, or pagination behavior (which lives only 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 compact sentences, front-loaded with the purpose and scoped to one company. The trailing endpoint citation ('GET /api/xml/3.0/contractor/list') is developer reference rather than agent-facing guidance, but it is short and costs little.

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

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

With no output schema, the description usefully lists the fields the reply contains (names, NIP, address, bank accounts, e-mails, payment days), which is the main thing an agent needs to know. Pagination details are covered by the schema; only ordering and result-size expectations are missing.

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

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

Schema description coverage is 100%, so company_program_id, limit and offset are fully documented in the schema, including the paging.next_offset hint. The description adds nothing parameter-specific, 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 (List) and resource (contractors = suppliers and customers) scoped to one company, and enumerates the returned fields. This clearly distinguishes it from siblings like saldeo_list_companies, though it never names an alternative explicitly.

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

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

Usage is only implied: the agent infers you list contractors for a given company_program_id. There is no explicit statement of when to prefer this over saldeo_search_documents or saldeo_list_companies, and no prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds output-shape information (ids grouped by document type) and the underlying endpoint POST /api/xml/3.0/document/getidlist. It does not mention rate limits or how large the grouped result can get, but it goes meaningfully beyond the annotations.

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

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

Three short sentences, front-loaded with the core scope, followed by the chaining instruction and the raw endpoint. No filler or restated title 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?

With no output schema, the description carries the burden of describing results, and it does so by naming the grouping categories. Paging is delegated to the schema. A little more on the reply structure (per-type lists plus paging) would make it complete for a 5-parameter 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%, so year, month, limit, offset, and company_program_id are all documented in the schema, including cross-references to saldeo_list_companies and paging.next_offset. The description only restates 'one company in one month folder' without adding format or edge-case guidance, 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 with scope: 'List the ids of all documents of one company in one month folder, grouped by type'. It also enumerates the grouping categories and points to saldeo_get_documents_by_ids, which separates it from saldeo_list_invoice_ids and saldeo_search_documents.

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?

'Feed the ids to saldeo_get_documents_by_ids' gives a clear usage context: this is a two-step id-retrieval tool, not a content fetcher. It does not state when to prefer this over saldeo_search_documents or explain that it returns no document bodies, so explicit exclusions are missing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds two genuine bits of context: this endpoint returns HR master data and "Contains personal data", which flags a privacy/GDPR sensitivity an agent should know before surfacing results. It still says nothing about permissions, result volume, or paging 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 tight sentences with the key capability and the data-sensitivity warning front-loaded. The trailing "Saldeo: GET /api/xml/3.0/employee/list" is cheap but is API trivia an agent doesn't need to select the tool.

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

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

For a read-only list tool with annotations, full schema coverage and no output schema, the description covers purpose, scope, payload contents and the personal-data caveat. Only the absence of any note about the paging envelope shape keeps it from being fully self-sufficient.

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 limit, offset and company_program_id are fully documented in structured fields, including paging semantics. The description adds no parameter-level detail beyond the implicit one-company scoping, 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 the employees"), scopes it to "one company (personnel module)", and enumerates the returned fields (names, acronym, HR master data). This clearly separates it from siblings such as saldeo_list_companies and saldeo_list_contractors.

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 company-scoped phrasing plus the pointer that company_program_id comes from saldeo_list_companies implies the right call context. However, there is no explicit when-to-use/when-not guidance and no comparison against alternatives like saldeo_list_contractors for people-related lookups.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description adds the scoping constraint (one company, one month folder) and the underlying endpoint POST /api/xml/3.0/invoice/getidlist for traceability. It does not mention that the reply is split into several paginated lists, one per document type, which is the main behavioral fact left implicit 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 compact sentences: the scope and document types come first, the follow-up tool second, with the raw endpoint appended as a terse reference. No filler or redundant restatement of 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 read-only id-listing tool with no output schema, the description covers what is returned (ids) and what to do with them next. The one gap is that it never says the response contains multiple separately paginated lists, leaving the agent to infer that limit/offset apply per document-type list.

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

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

Schema description coverage is 100%, so all five parameters including limit/offset paging semantics are already documented. The description only reinforces the company + year + month folder grouping, which the schema already conveys, so it adds little beyond the structured fields. 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 invoice ids) and enumerates exactly which document types are covered (invoices, corrective invoices, pre-invoices, corrective pre-invoices), scoped to one company and one month folder. It implicitly separates itself from saldeo_list_invoices by emphasizing ids-only, but never names that sibling to make the contrast explicit.

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 sentence 'Feed them to saldeo_get_invoices_by_ids' gives a concrete next step and thereby implies this is a two-phase id-then-detail workflow, which is real usage guidance. It stops short of stating when to prefer saldeo_list_invoices instead, or any prerequisites such as needing a valid company_program_id first.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint and the returned field set, but says nothing about pagination behavior (deferred to schema) or result ordering, so it adds only modest context beyond structured data.

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, front-loading the resource and scope before the endpoint reference. No filler.

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

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

For a read-only list tool with complete schema descriptions and annotations, the description is essentially complete: it states scope and the fields returned. Lacking only explicit sibling routing and pagination notes, both partly covered elsewhere.

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 limit, offset, and company_program_id are fully documented in the schema. The description adds no syntax or format detail beyond that, making baseline 3 appropriate.

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

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

States a specific verb (List) and resource (sales invoices), plus meaningful scope: only invoices marked for export, for one company, with the fields returned enumerated (number, dates, contractor, line items, amounts). This separates it from saldeo_list_invoice_ids (IDs only) and saldeo_get_invoices_by_ids, though it does not name those siblings 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?

No explicit when-to-use guidance or alternatives are named. The 'marked for export' scope implies a use case, but an agent is left to infer when this beats saldeo_list_invoice_ids or saldeo_get_invoices_by_ids. No prerequisites beyond company id.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered structurally. The description usefully adds that fields combine with AND and identifies the underlying BY_FIELDS policy, but says nothing about pagination behavior, result limits, or return ordering 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?

The description is tight and front-loaded: scope and search semantics come first, endpoint metadata last. Every sentence carries information relevant to invoking the tool correctly.

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 read-only search tool with fully documented schema and no output schema, the description covers purpose, search semantics, and the AND constraint. It is nearly complete, with only minor omitted details such as how empty results or paging are surfaced.

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 parameter definitions are already documented. The description adds a meaningful constraint not expressed in the schema: at least one of document_id, number, nip, or guid must be supplied, and multiple such fields are ANDed together.

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 ('Find') and resource ('documents'), plus the scope 'of one company by field'. It implicitly distinguishes field-based search from sibling list/get-by-ID tools, though it does not name an alternative 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?

It states that at least one search field is required and that multiple fields combine with AND, which is useful usage context. However, it never says when to prefer this over saldeo_list_document_ids or saldeo_get_documents_by_ids, leaving alternative selection implicit.

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