yuki-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.5.1
Disambiguation3/5
Several tools have overlapping purposes: get_transactions, get_transaction_details, and get_gl_transactions_detailed all relate to transaction data, while get_document, download_document, and get_transaction_document all revolve around retrieving document content or metadata. Descriptions help differentiate them, but an agent may need to read carefully to pick the right one.
Naming Consistency5/5
All tools follow a consistent verb_noun snake_case pattern (get_, process_, upload_, download_, list_, search_, etc.). No mixed conventions or odd variations; the naming is predictable and readable.
Tool Count2/5
With 31 tools, this server is over the recommended range for a coherent set. While the accounting/ERP domain is broad, the count feels heavy and may overwhelm an agent, especially with many document and transaction retrieval variants.
Completeness4/5
The tool set covers a wide range of Yuki operations: administrations, contacts, GL accounts, transactions, invoices, document upload/download/search, workflow, and fiscal queries. Minor gaps exist (e.g., no direct update/delete for invoices or a single-contact getter), but most core workflows are supported.
Average 4.1/5 across 31 of 31 tools scored. Lowest: 3.3/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 2 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses some behavioral traits, such as searchOption filtering and tab scoping, but it directly contradicts the schema by saying 'use 0 to search all tabs' while the schema specifies -1 as the default and all-tabs value. This misleading instruction undermines transparency. There are no annotations to provide additional safety or behavior context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably short and front-loaded, with the purpose stated first. However, it contains a factually incorrect instruction about tabID that should be corrected, and the inclusion of this error makes the structure less reliable. It earns a middling score for conciseness because it could be accurate and equally brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, no output schema, and no annotations, the description should provide more guidance on pagination, date filters, sorting, and expected return behavior. It only covers searchOption and tabID, and even that is flawed. The tool is not adequately described for safe, correct invocation without additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds minimal new meaning beyond re-stating enum values. More importantly, the tabID guidance conflicts with the schema, actively misleading the agent about a critical parameter. This detracts from parameter clarity rather than enhancing it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search for documents in a Yuki archive folder by text' with a specific verb and resource, distinguishing it from sibling tools like list_documents. It also briefly previews key filtering parameters, making the tool's purpose immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit prerequisite instruction: 'Call get_document_folders first to find the folderID.' It also explains how searchOption and tabID scope the search. While it doesn't explicitly state when not to use this tool versus alternatives, the context is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only mentions that it returns the Yuki response with a document ID. It does not reveal important side effects like the 'process' flag defaulting to true (immediate finalization), contact creation/linking behavior, or any permissions/error conditions. For a mutating tool, this is insufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences, each adding value: it states the action, lists accepted inputs, and describes the return value. It is front-loaded with the primary purpose and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex with 14 parameters and nested objects, but the schema covers parameters well. The description explains the return value since there is no output schema. However, it omits important contextual behavior such as the immediate processing/finalization, contact handling when contactCode is provided, and potential side effects. This is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (79%), so the schema already documents most parameters. The description adds a high-level grouping ('invoice totals, supplier contact, line items') but does not provide additional semantics beyond the schema. It does mention the optional base64 PDF attachment, which is redundant with the schema's documentBase64 description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Book an incoming purchase invoice') and the target resource ('Yuki'). It is distinct from sibling tools like process_sales_invoice by specifying 'purchase invoice.' It also mentions what is accepted and what is returned, fully clarifying the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for booking incoming purchase invoices, but it does not provide explicit when-to-use or when-not-to-use guidance relative to alternatives such as process_sales_invoice or upload_document. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the return format (base64 string, fileName, fileDataBase64) and notes the document must be archived, but omits details about authentication, rate limits, or error behavior. Some context is added, but gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the action, and contains no redundant wording. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter download tool with no output schema, the description covers the essential workflow: find the ID, download the archived document, and receive the file name and base64 data. It lacks details on error handling but is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100% and the parameter description already mentions it is from list_documents or search_documents. The tool description reinforces this workflow but adds minimal new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it downloads an archived document from Yuki as a base64-encoded string, using a specific verb and resource. It adds distinguishing details like 'archived' and 'base64-encoded', but does not explicitly differentiate from sibling tools such as get_document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance to first use list_documents or search_documents to find the document ID, which is a clear prerequisite. It does not exclude alternatives or explain when not to use the tool, but the given context is helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for behavioral disclosure. It mentions that it retrieves 'all' GL accounts and defaults to today's date if no date is provided, which is useful. However, it does not disclose potential side effects, permissions, return format, or other behavioral nuances. Given the read-only nature, this is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action and immediately followed by usage and default behavior. Every sentence earns its place with no wasted words or redundant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only 2 optional parameters and no output schema, the description covers the essential aspects: purpose, usage, and default date behavior. It does not explain return values, but that is not required since there is no output schema. It could mention sibling alternatives for full completeness, but the tool is simple enough that this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 reinforces the date parameter's default behavior, but it does not add meaning beyond what the schema already provides. Since both parameters are well-documented in the schema, the description adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves all GL accounts with their balance at a given date, using a specific verb and resource. It also provides examples of use cases (finding account codes, financial snapshot). However, it does not explicitly distinguish itself from sibling tools like get_gl_accounts_fiscal, 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: 'Use this to find account codes... or get a financial snapshot.' It also notes the default behavior for date. However, it does not mention alternatives or when not to use this tool, so it lacks the explicit exclusions needed for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool returns specified fields and optionally filters by due date, which is helpful. However, it does not mention any side effects, pagination behavior, default sort order, or limitations, leaving some behavioral aspects undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the primary purpose. The second sentence efficiently lists the return fields and the optional filter without extraneous details. Every sentence earns its place, making it concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lists the key return fields (creditor name, reference, due date, open amount, currency) which is valuable since there is no output schema. It also explains the optional filter. However, it does not mention pagination, defaults (e.g., sort order), or the behavior of includeBankTransactions, which are covered by the schema but not the description, leaving slight gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all four parameters. The description adds little beyond referencing dateOutstanding as an optional filter, but this is redundant with the schema. Therefore, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves outstanding (unpaid) purchase invoices from Yuki, specifying the resource (purchase invoices), status (unpaid), and source (Yuki). It distinguishes itself from sibling tools like get_sales_invoices by explicitly mentioning purchase invoices and outstanding status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when outstanding purchase invoices are needed, and the optional dateOutstanding filter provides a clear context. However, it does not explicitly mention when not to use this tool or suggest alternatives, such as get_missing_invoices or get_transactions, so the guidance is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool performs a read-only existence check and retrieves amount/status, which is useful. However, it does not mention what happens if the reference is not found, whether any side effects occur, or any permissions needed. The behavioral traits are partially disclosed but not fully.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the key purpose and expected output. Every word contributes meaning, and there is no redundancy or padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup tool with two parameters (one required) and full schema coverage, the description provides sufficient context: it explains what the tool does and what it returns (open amount and status). The absence of an output schema is somewhat mitigated by the explicit mention of the retrieved fields. Missing details about error handling are acceptable for such a basic read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with clear descriptions (reference format and default for administrationId). The description adds little beyond what the schema already states, only reinforcing that 'reference' refers to the invoice reference and that the output includes open amount and status. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: check if an outstanding invoice with a given reference exists and retrieve its current open amount and status. It uses specific verbs ('check', 'retrieve') and specifies the resource (outstanding item/invoice), distinguishing it from sibling tools like get_transactions or get_transaction_document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need to verify an invoice's existence and get its current open amount/status) but provides no explicit alternatives or exclusions. It does not mention that other tools like get_sales_invoices or get_purchase_invoices might be alternatives, so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that returned items are those that could not be processed automatically, which is a useful behavioral trait. However, it does not explicitly state that the operation is read-only, mention any permissions needed, or describe the response structure beyond 'workflow items.' While 'Retrieve' implies non-mutating behavior, the description lacks deeper transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It front-loads the primary action ('Retrieve...') and then provides a concise explanation of what the workflow items are, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one well-documented parameter and no output schema, the description adequately conveys the tool's purpose and the nature of the returned items. It could be marginally improved by noting the response format or typical fields, but overall it provides enough context for an agent to decide when to use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the single parameter administrationId, including its type and default behavior (YUKI_DOMAIN_ID env var). The description adds no additional meaning about this parameter, so it does not go beyond the 100% schema coverage already present.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Retrieve the Yuki backoffice workflow items.' It clearly defines what these items are (unprocessed purchase and sales invoices awaiting accountant review), which distinguishes this from sibling tools like get_sales_invoices or get_purchase_invoices that would return all invoices, not just pending workflow items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use this tool to retrieve items that need manual review and booking. However, it does not explicitly state when to use this tool over alternatives like get_missing_invoices or process_sales_invoice, nor does it mention any exclusions or prerequisites beyond the optional administrationId parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does add value by explaining that fiscal=true includes fiscal corrections and matches Yuki fiscal reports. However, it does not explicitly state that the operation is read-only, mention any access requirements, or describe the return structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and object, adds the key optional flag, and contains no filler or redundancy. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core function and the fiscal nuance, but given that there is no output schema, it does not explain the return format or any edge-case behavior. It also lacks explicit usage guidance relative to sibling tools. For a simple revenue getter, it is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 adds meaning beyond the schema by clarifying the fiscal parameter with the context 'matches Yuki fiscal reports', which is extra value. Other parameters are adequately covered by the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieve') and names the exact resource ('net revenue (netto-omzet)') with clear scope ('for an administration within a date range'). This clearly distinguishes it from all 31 sibling tools, none of which target revenue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for net revenue queries with an optional fiscal flag, but it does not explicitly state when to use this tool versus alternatives or provide any exclusions. The fiscal flag explanation is more of a parameter detail than a usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does explain the create/update logic and the return value, which is useful. However, it omits crucial details such as whether updates are partial or full replacements, what happens to omitted fields, and error handling, leaving ambiguity for a 20-parameter write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the primary purpose, and every sentence contributes value: the operation, the conditional logic, and the return value. There is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 20 parameters and no output schema, the description covers the core upsert concept and the return value but leaves open important behavioral details such as update semantics (partial vs full), required fields for creating a new contact (only fullName is required in schema), and any side effects. It is minimally viable but has clear gaps in operational guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, meaning half the parameters lack descriptions in the schema. The description adds meaningful context for contactCode (that it identifies existing records) and implicitly maps 'customer or supplier' to the contactType parameter. However, it does not compensate for the lack of descriptions for the other undocumented parameters, and overall adds limited parameter-level detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the operation ('Create or update a contact'), the target resource ('in Yuki'), and the distinguishing behavior based on contactCode. It explicitly differentiates the tool from its read-only siblings by stating it performs writes and explains the upsert nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for use: it indicates when a record is updated vs created based on contactCode. It does not explicitly state exclusions or alternatives, but the upsert behavior itself gives sufficient usage guidance, especially with no competing contact-creation tools among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. The verb 'list' implies a read-only operation with no side effects, which is helpful but not explicitly stated. The description does not disclose potential errors, authentication requirements, or whether all categories are returned. It is adequate for a simple getter but lacks deeper behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. The first sentence states the action, the second provides actionable guidance. Every word earns its place, and the structure is front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one optional parameter, no output schema), and the description explains its purpose and how to use the result. It does not describe the return format in detail, but the mention of 'returned GL codes' gives enough for the agent to understand the output. A brief note on the return structure would push it to a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the single parameter administrationId is fully described in the schema with type and default. The description adds no additional parameter information, so it meets the baseline 3 without exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists cost categories (GL cost accounts) for document uploads, using a specific verb and resource. It distinguishes itself from sibling tools like get_gl_accounts by scoping to document uploads, and explicitly links to upload_document.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context: 'Use the returned GL codes as the costCategory parameter in upload_document.' This tells the agent when and how to use the tool. However, it does not mention exclusions or alternatives, such as using get_gl_accounts for non-upload scenarios, so it falls slightly short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It implies a read-only operation by using 'List', but does not explicitly state whether there are side effects, authorization requirements, or pagination behavior. It adds the connection to upload_document but not deeper behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the action and then give usage context. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description covers the main purpose and a specific use case. It doesn't describe the return structure, but that can be inferred. It's mostly complete, though slightly more detail on what constitutes an 'archive folder' might help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter administrationId is fully described in the schema (including GUID format and default to env var), so the description adds nothing beyond that. Baseline 3 is appropriate since schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all archive folders') and the scope ('in the Yuki administration'), which distinguishes it from sibling tools like list_documents or search_documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance to use this tool to find the correct folder ID for upload_document, giving a clear use case. However, it does not mention when not to use it or alternative tools, so it lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of disclosing behavioral traits. It identifies the operation as 'Retrieve', which implies read-only, and adds context about the blocking nature of the questions. However, it does not explicitly mention side effects, return format, or authentication requirements, leaving some gaps typical of a simple getter tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with the first sentence front-loading the core action and the second adding necessary context. There is no redundancy or irrelevant detail, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple one-parameter getter with no output schema, so the description need not explain return values in depth. It adequately covers the purpose, the domain meaning of 'outstanding backoffice questions', and the context of processing blocks. Minor omissions like pagination or response structure are acceptable given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already includes a fully described parameter (administrationId) with 100% coverage. The description does not add extra meaning beyond the schema, so the baseline score of 3 applies. The mention of 'for an administration' slightly reinforces the parameter's purpose but not significantly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Retrieve' and a specific resource 'outstanding backoffice questions', immediately clarifying the tool's purpose. It also explains what these questions are (raised by the accountant and requiring response before processing), which distinguishes it from sibling tools like get_missing_invoices or get_workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when there are outstanding backoffice questions that need a response before related documents can be processed. This provides clear context, though it does not explicitly name alternative tools or exclusions. The guidance is sufficient for an agent to understand the appropriate scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the return structure (accountID, accountDescription, startBalance) and the fiscal year scope, but does not explicitly state read-only nature or behavior for edge cases (e.g., missing year, financialMode differences).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: purpose, return fields, and usage context. Every sentence adds value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description is adequate for a simple read tool: includes purpose, return shape, and use case. However, it doesn't mention the role of financialMode or administrationId, though those are covered by the schema. Overall complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already documented in the schema. The description adds no additional parameter explanation beyond repeating 'fiscal year' which matches yearId.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb 'Retrieve', clear resource 'opening balances (beginbalansen) per GL account for a fiscal year', and states return fields. Unambiguous and distinct from sibling tools like get_gl_accounts or get_gl_transactions_detailed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states use case 'for year-over-year balance verification', but does not mention alternatives or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must state behavioral traits. It discloses the return fields and the scope ('all journal entries'), but omits details like pagination, ordering, or any potential limits. It also does not explicitly state whether this is a safe read-only operation, though 'Retrieve' implies it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, all content-bearing, with the main action first and supporting details after. No redundant or generic statements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description lists return fields and gives a practical workflow. It does not mention pagination or other runtime behavior, which is a minor gap, but the tool's purpose and prerequisites are well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already provides descriptions for all four parameters (100% coverage), so baseline is 3. The description reinforces glAccountCode and date range, and adds a pointer to get_gl_accounts, but does not add further meaning for the optional administrationId or parameter formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb ('Retrieve') and resource ('journal entries for a specific GL account code within a date range'), and the return fields are listed. It clearly distinguishes itself from sibling tools like get_transaction_details by focusing on GL account-level filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use case: 'Use this for bank transactions' and prerequisite: 'find the bank GL code with get_gl_accounts first'. However, it does not name any alternative tools to avoid, so it's clear on when to use but not when not to.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It adds value by specifying the return fields and the workflow, but it omits details about pagination (startRecord, numberOfRecords), date filtering, and potential limitations. The description is not misleading, but it lacks some operational context that would be useful for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, each serving a distinct purpose: what the tool does, the prerequisite, and the follow-up usage. The description is front-loaded with the primary action, and there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core workflow (folder → list → get/download) and specifies key return fields. Although there is no output schema, the description mentions what is returned. The schema handles parameter details, and the description provides sufficient context for an agent to invoke the tool correctly, though it could mention pagination or filtering behavior explicitly for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 all 6 parameters. The description lightly reinforces the folderId parameter by referencing get_document_folders, but adds no additional meaning about the parameters themselves, such as date formats or sort order behavior. This meets the baseline for well-documented schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list documents), specifies the resource (Yuki archive folder), and lists the return fields (document IDs, file names, dates, amounts). It distinguishes from siblings by explicitly contrasting with get_document_folders and get_document/download_document, making the tool's role in the workflow clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear prerequisite guidance ('Call get_document_folders first to find the correct folder ID') and suggests follow-up usage with get_document/download_document. However, it does not explicitly mention alternatives like search_documents or state when not to use this tool, so it misses the 'when-not' or explicit alternative comparison needed for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing side effects. It states the tool creates and books (a mutation), optionally emails the customer, and returns the Yuki response with a document ID. However, it does not clarify that 'booking' is typically irreversible or that specific permissions may be required, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, front-loaded with the main action, and every sentence adds value. There is no fluff or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (12 parameters, nested objects, no output schema), the description covers the key behavioral aspects: creation, booking, optional email, and return value with document ID. The detailed schema fills in the rest. It lacks explicit guidance on failure scenarios or prerequisites, but is otherwise complete for a create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers 92% of parameters with detailed descriptions, so the baseline is 3. The description adds minimal extra meaning by grouping parameters into 'invoice header, contact, and line items' and mentioning the email option, but it does not substantially enhance the schema's parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates and books a sales invoice in Yuki, which is a specific action on a specific resource. It also lists the accepted components (header, contact, line items) and the optional email side-effect, making its purpose unambiguous. This distinguishes it from sibling tools like process_purchase_invoice and process_journal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for sales invoices, and the verb 'create and book' gives a direct usage context. However, it does not explicitly contrast with alternatives like process_purchase_invoice or state when not to use it, so it provides clear context but no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses key requirements (base64-encoded string) and a dependency (folder ID from get_document_folders), but does not describe response behavior, error conditions, or mutation characteristics beyond the act of uploading. This is useful but incomplete 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences with no filler. It front-loads the purpose, then adds usage context, a requirement, and a prerequisite. Each sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 10 parameters and no output schema, the description covers the core usage, requirement, and prerequisite. It could mention the response or success/failure behavior, but given the rich schema, the description is adequate for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for all 10 parameters. The description adds minimal extra meaning, referencing base64 encoding and folder retrieval, both already present in the schema. It does not introduce new parameter-specific details, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Upload') and resource ('Yuki archive'), and distinguishes it by mentioning base64 encoding, which differentiates it from the sibling upload_document_from_path. The use case ('attach source documents to purchase invoices or store receipts') adds clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use it ('Use this to attach source documents to purchase invoices or store receipts') and a clear prerequisite ('Call get_document_folders first to find the correct folder ID'). It does not explicitly mention when not to use it or alternatives like upload_document_from_path, so it lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It implies a read operation ('Retrieve') and lists return fields, which is useful. However, it does not disclose potential error conditions (e.g., invalid yearId), data source behavior, or whether results are paginated. For a simple read tool, this is acceptable but not rich in behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences deliver purpose, return content, and a use case without wasted words. The first sentence states the action and primary input; the second clarifies output and application. Excellent structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only tool with two parameters and no output schema, the description fully covers what the agent needs to know: what it does, what it returns, and when to use it. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for both parameters (yearId as integer, administrationId with default). The description reinforces that yearId is a fiscal year and hints at the date-to-period mapping but adds no new parameter-specific details beyond schema, matching the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Retrieve the fiscal period table' and specifies the return content (period numbers, names, start/end dates). This clearly distinguishes it from sibling tools like get_transactions or get_gl_accounts, which serve different data retrieval purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a concrete use case: 'translate a transaction date into a period name for reports' with a specific example. While it doesn't explicitly mention alternatives, the context makes it clear this is for fiscal period mapping, which is sufficiently distinct from sibling tools. No exclusion criteria are stated, but the guidance is actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal a key behavior: 'Reads and encodes the file internally — no need to pass base64 strings.' However, it does not disclose other behavioral aspects such as required permissions, error conditions (e.g., missing file), or side effects. This is partial disclosure, but not comprehensive enough for a higher score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: three sentences, each serving a distinct purpose. The first gives the action, the second explains a key internal behavior, the third provides usage alternatives and a prerequisite. Every sentence earns its place with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 10 parameters (though only 1 required), no output schema, and no annotations. The description gives the core purpose, the alternative, and a prerequisite, which is helpful. However, it does not mention any return value or error scenarios. Given the complexity and lack of output schema, this is a moderate gap; the description is complete enough for basic usage but not fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all 10 parameters with descriptions, so schema coverage is 100%, giving a baseline of 3. The description adds little extra parameter semantics beyond the schema; it mentions the internal encoding to explain why base64 isn't needed, but this is more behavioral than parameter-specific. Thus, no reason to raise above the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Upload a PDF from a local file path to the Yuki archive.' It uses a specific verb + resource. It also distinguishes itself from the sibling tool upload_document by noting to 'Use this instead of upload_document when the file is available on disk.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it names the alternative tool (upload_document) and the condition for choosing this tool ('when the file is available on disk'). It also gives a prerequisite step ('Call get_document_folders first to find the correct folder ID'). This fully satisfies the when/alternatives criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It explains the lookup behavior and the exact name requirement, but it does not disclose what happens if the name is not found, whether authentication is needed, or the return format (e.g., plain GUID string).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler: the first states the function, the second gives usage context, and the third points to the alternative. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter lookup with no output schema and no annotations, the description covers purpose, usage, and alternative. It lacks explicit error/no-result behavior, but overall it is adequately complete for its low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 reinforces the 'exact name' concept already in the schema but adds no new parameter semantics beyond linking the parameter to the tool's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'look up' and clearly states the resource ('the GUID of a Yuki administration'), distinguishing it from the sibling tool get_administrations, which lists all administrations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool ('Use this to resolve an administration name to the ID required by other tools') and when to use the alternative ('For a full list of administrations and IDs use get_administrations').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It clearly signals a read-only operation via 'Retrieve' and enumerates the returned fields (debtor name, reference, due date, open amount, currency). It does not disclose default sort behavior or the effect of includeBankTransactions, but these are covered in the schema and do not undermine the core transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two sentences, front-loading the purpose and output fields, with the optional filter in the second sentence. Every word earns its place; there is no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with no output schema, the description provides the essential return fields and the optional filter. It omits default sort order and includeBankTransactions behavior, but those are documented in the schema. Overall, the description plus schema is sufficient for a human or AI to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all 4 parameters. The description's mention of dateOutstanding as a 'due date cutoff' is redundant with the schema's existing explanation ('ISO date string... returns only items outstanding as of this date'). No additional parameter meaning is provided 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Retrieve' and clearly identifies the resource as 'outstanding (unpaid) sales invoices from Yuki.' This distinguishes it from siblings like get_purchase_invoices and process_sales_invoice, and the scope ('outstanding/unpaid') is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for listing unpaid sales invoices and mentions the optional dateOutstanding filter, giving context on when to use it. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses a critical behavioral rule (amounts must sum to zero or Yuki rejects) and implies a write operation. It does not mention permissions or return behavior, but the disclosed validation rule is highly valuable and non-obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and the CAPITALIZED warning earns its place. Every sentence adds value and there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description and schema together provide sufficient context for a complex tool with no output schema. The description covers purpose and key constraint, while the schema covers all parameters. It could mention return behavior, but that is not essential for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description reinforces the sum-to-zero rule (already in the schema) but does not add new parameter-level semantics beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Post'), a specific resource ('general journal entry (memoriaal)'), and concrete use cases ('bank reconciliation, corrections, or custom bookings'). This clearly distinguishes it from sibling tools like process_sales_invoice and process_purchase_invoice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit use cases (bank reconciliation, corrections, custom bookings) and the term 'general journal entry' implies it is for non-invoice entries. However, it does not explicitly say when not to use it (e.g., 'use process_sales_invoice for sales invoices').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It states the pagination behavior ('up to 100 contacts per page'), the return fields ('IDs, codes, names, and contact details'), and the special case for empty searchValue. While it does not explicitly say 'read-only', the verb 'search' and 'Returns' imply a safe operation. This is sufficient for a search tool, though an explicit read-only note would improve clarity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose. Every sentence adds value: the first defines the tool's function, and the second covers pagination and the all-contacts behavior. There is no fluff or redundancy (the empty-searchValue note is arguably duplicated in the schema, but it is a key usage point). Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately covers return values and pagination, which are essential for using the pageNumber parameter. It also highlights the behavior when searchValue is omitted. It does not mention the searchOption enum values or the domainId default, but those are already in the schema. The description is complete enough for a search tool, though it could mention that it is read-only to fully round out the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all 5 parameters (100% coverage), so the description need not compensate. The description adds little beyond the schema: it summarizes the search fields and repeats the empty-searchValue behavior already documented in the schema. The output note about return fields is not parameter semantics. Thus, the description does not significantly enhance parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Search for Yuki relations (customers/suppliers) by name, code, VAT number, or other fields.' It specifies the resource (relations) and the action (search), with a clear scope of usable fields. It distinguishes itself from sibling tools like get_gl_accounts or process_invoices, which target different entities or operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is a search tool for relations, with a specific usage hint: 'Omit searchValue (or pass an empty string) to retrieve all contacts.' This implies when to use the tool, but it does not explicitly mention alternatives or when-not-to-use. Sibling tools are mostly for other data types, so the context is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that the operation is a read-only retrieval, lists the exact return fields (creditor name, open amount, date, bank description), and gives UI context. It lacks details on pagination or ordering, but these are not critical for this simple read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: purpose, return value details, and next-step resolution guidance. No redundant or fluff content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional param, no output schema, no annotations), the description provides a complete picture: what it does, what it returns, and how to act on the results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter (administrationId) is fully described in the schema (100% coverage). The description adds no additional parameter details, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Retrieve bank payments that still need a matching purchase invoice', immediately distinguishing it from sibling tools like get_purchase_invoices or get_transactions. It also ties to a UI path, reinforcing scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly indicates this is for unmatched payments and suggests resolution tools (upload_document, process_purchase_invoice), but doesn't explicitly state when NOT to use it or directly contrast with alternatives like get_transactions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear the full burden of behavioral disclosure. It clarifies that the tool returns metadata and not the binary, and it names the returned fields. However, it does not mention error behavior (e.g., for non-archived documents), authorization requirements, or any side effects. While it avoids contradiction, it misses opportunities to add context beyond the return value list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short, purposeful sentences. The first sentence states the primary function and output, the second guides to finding IDs, and the third points to the download sibling. No fluff; every sentence earns its place and is front-loaded with the verb+resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given lack of output schema, the description compensates by listing returned fields (file name, folder, date, amount, status). It also provides sufficient navigation among sibling tools (list_documents, search_documents, download_document). It could mention failure modes or authentication, but for a simple metadata retrieval tool, the coverage is adequate and well directed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100% so baseline is 3, but the description adds meaning by explaining that documentId can be obtained from list_documents/search_documents, and administrationId defaults to YUKI_DOMAIN_ID env var. This enriches the schema descriptions, especially around where parameter values come from.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Retrieve metadata for a single archived document by its Yuki document ID.' It lists specific return fields (file name, folder, date, amount, status) and distinguishes itself from siblings like download_document (binary) and list_documents/search_documents (finding IDs). This is a specific verb+resource definition with explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use this tool vs alternatives: 'Use list_documents or search_documents to find document IDs. To download the file binary use download_document.' It clearly states prerequisites (need a Yuki document ID) and directs to other tools for discovery and binary retrieval, covering both when and when-not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses a key behavioral trait (inclusion of fiscal corrections, i.e., fiscale stand) and the context of aligning with Yuki fiscal reports. It doesn't mention pagination or response format, but the core read behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action and resource, followed by usage context and the alternative. Every sentence is purposeful, with no repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what the tool does, what data it includes, when to use it, and which sibling to use instead. Since there is no output schema, it does not describe the return structure, but the core usage context is sufficiently complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters (date, administrationId) with descriptions, achieving 100% schema coverage. The tool description adds no additional parameter-specific detail beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves all GL accounts with balances including fiscal corrections. It explicitly distinguishes itself from the sibling tool get_gl_accounts by contrasting the fiscal view with the commercial view, making its purpose instantly clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: use for balance sheet and P&L views matching Yuki fiscal reports, and use get_gl_accounts instead for commercial/operational views. It names the alternative and the exact conditions for each choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It discloses meaningful behaviors: the richer fields returned, the ability to fetch all accounts via an empty code, and the intended use case. While it does not mention pagination, errors, or explicit read-only status, the verb 'Retrieve' and the field list convey a safe query operation sufficiently for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the main purpose, then the distinctive richer fields, then a concrete use case. No wasted words; every sentence earns its place. It is concise yet informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, no output schema, and no annotations, the description is reasonably complete. It identifies required date range, optional account filter, and the specific rich fields, making the tool invocable. Minor gaps remain around return formatting and pagination, but the stated use case covers the likely agent need.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 adds little beyond the schema: it repeats the 'leave empty for all accounts' guidance already present on glAccountCode and does not clarify startDate, endDate, or financialMode semantics. It adds minor context by suggesting which GL accounts (depreciation, salary) might be relevant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Retrieve detailed transaction data for a GL account within a date range.' It explicitly distinguishes itself from sibling get_transactions by listing the richer fields returned, leaving no ambiguity about what this tool uniquely provides.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description names the alternative tool get_transactions and clarifies when to prefer this one ('Use this to find the last period in which a depreciation or salary booking was made'). It also gives a practical filter instruction ('Leave glAccountCode empty to fetch all accounts'), providing clear context for when to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden of behavioral disclosure. It states that the file is returned as base64 and that the response includes fileName and fileData, which is transparent about the output format and structure. It does not mention potential failure modes or auth requirements, but for a read-only download tool, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the verb 'Download' and the resource, and includes all essential information without fluff. Every sentence earns its place: the first states the action and output format, the second provides the input source and return fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the absence of an output schema, the description adequately explains the return value (fileName and fileData) and the input (transaction ID). It covers the practical usage context well, though it doesn't mention error handling or size limitations, which are not critical for a basic download tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by specifying that the transaction ID comes from get_gl_transactions_detailed, going beyond the schema's generic 'Transaction ID (from the id or hID field...)'. This cross-reference helps the agent understand the correct source and usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool downloads a source document (PDF) for a booked transaction and returns it as base64. It specifies the resource (transaction document) and the action (download), and distinguishes itself from generic document tools by referencing get_gl_transactions_detailed as the source of the required transaction ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by instructing to use the transaction ID from get_gl_transactions_detailed, which implies this is the tool for transaction-specific documents. It does not explicitly mention alternatives or exclusions, but the specificity of the instruction gives adequate guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It effectively communicates that this is a read-only retrieval (via 'Retrieve') and describes the exact return contents, including active/inactive status. It does not mention authorization requirements or potential large response sizes, but for a simple scheme lookup, the coverage is adequate and honest.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: 1) what the tool does, 2) what it returns, 3) when to use it and the alternative. It is front-loaded with the primary purpose, every sentence carries useful information, and there is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with a single optional parameter and no output schema, the description fully equips an agent: it explains the return format and use cases. It distinguishes from the most likely sibling tool (get_gl_accounts) and provides enough semantic detail to select it correctly. There is no indication of pagination or hidden complexity, so the description is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the only parameter (administrationId) with a clear description and default behavior. With 100% schema description coverage, the description adds no new parameter-level meaning, which aligns with the baseline of 3. The description's mention of 'for an administration' gently reinforces the schema but does not expand on it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retrieve'), the resource ('complete GL account scheme'), and the scope ('for an administration'). It lists the returned fields (account code, type, subtype, description, status), making the tool's purpose unmistakable. It also differentiates from the sibling 'get_gl_accounts' by explicitly noting that tool is for balances.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'Use this to validate GL codes before booking or to build account pickers.' It also names an alternative, 'For current balances use get_gl_accounts instead,' which tells the agent exactly when to choose a different tool. This satisfies both positive and negative usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the operation type ('List'), the authorization context ('accessible with the configured API key'), and the primary purpose (discovering administrationID). It does not mention return format or error cases, but for a simple listing operation with no parameters, this is sufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the verb and resource, then add a critical usage hint. No filler words or redundant details. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 params, no output schema), the description covers what the tool does, what it returns (list of administrations), how it's authenticated, and how to use it. It is fully complete for its context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline for this dimension is 4. The description adds value by explaining the purpose of the tool's output rather than needing to clarify parameter syntax. No parameter information is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and identifies the exact resource ('Yuki administrations (companies)'). It clarifies the scope ('accessible with the configured API key') and distinguishes this from the sibling tool 'get_administration_id' by implying that this returns all administrations rather than a specific one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs 'Run this first to discover the correct administrationID to pass to other tools,' giving clear when-to-use guidance and explaining how the output is consumed by other tools. This is strong contextual usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It fully covers the key behavioral aspects: no restart required, sessions invalidated for changed/removed keys, unchanged keys keep cached sessions, and returns a diff. This is comprehensive and beyond typical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the primary purpose, and every sentence provides meaningful information: usage scenario, behavioral consequences, and return value. No redundant or vague wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description clearly explains what the tool returns (a diff). It covers the tool's purpose, trigger condition, effect on sessions, and return value, making it complete for the tool's moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 the 'path' parameter including its defaults. The description adds no additional meaning beyond the schema, which aligns with the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: reloading the administrationId → apiKey map from a JSON keys file without restarting the MCP server. This is a specific verb+resource combination that clearly differentiates it from the sibling tools, which are all read/process operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use it: after a new key has been generated externally (e.g., via create_api_key flow) to make it immediately usable for SOAP calls. This provides clear contextual guidance, and the effects (session invalidation) are clearly explained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![yuki-mcp MCP server](https://glama.ai/mcp/servers/CodeMill-Solutions/yuki-mcp/badges/card.svg)](https://glama.ai/mcp/servers/CodeMill-Solutions/yuki-mcp)

Score Badge

Copy to your README.md:

[![yuki-mcp MCP server](https://glama.ai/mcp/servers/CodeMill-Solutions/yuki-mcp/badges/score.svg)](https://glama.ai/mcp/servers/CodeMill-Solutions/yuki-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/CodeMill-Solutions/yuki-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server