Bukku MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds one genuinely behavioral fact – the contact code must be unique, so duplicates will fail – but says nothing about permissions, side effects, or what a successful call returns.

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

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

Two short sentences, front-loaded with the WRITE marker and the resource, then the key constraint. Every clause carries information and nothing is padded.

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

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

With 11 parameters, 4 of them required, entity-type conditional requirements, and no output schema, the description is too thin to call this correctly – it doesn't explain required-field rules, the MyInvois-dependent entity_type semantics, or what is returned on success.

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

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

Schema description coverage is 73%, so the schema already documents most parameters, and the one parameter the description expands on (contact_code's allowed characters and 15-char limit) merely restates the schema's pattern and maxLength. Nothing is said about the four required fields (legal_name, contact_code, entity_type, types) or the entity-type/reg_no/tax_id_no interdependencies.

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

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

States a specific verb (create) and resource (contact), scopes it to customer/supplier/employee, and names the endpoint POST /contacts. It is trivially distinguishable from siblings like bukku_get_contact and bukku_list_contacts.

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

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

The 'WRITE:' prefix signals that this is a mutating call, but the description gives no guidance on when to create vs. update or when not to use it. No alternatives or prerequisites are named, leaving routing entirely to inference from the name.

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

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

Beyond the annotations, it discloses critical side effects: draft does not post to the ledger, ready finalizes and affects the books, and MyInvois VALIDATE submits to LHDN and 'cannot be taken back.' It also explains conditional requirements for payment_mode and myinvois_action.

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

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

The description is dense but front-loaded and well structured: WRITE first, then status effects, payment dependencies, MyInvois requirements, lookup guidance, and endpoint. Every sentence adds relevant information.

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

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

For a 16-parameter create tool, the description covers the most important behavioral and conditional requirements. It does not describe the response or duplicate-prevention behavior, but the rich schema and annotations cover much of the remaining detail.

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

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

Schema coverage is high at 81%, so many parameters are already documented. The description adds important conditional semantics for status, payment_mode, and myinvois_action, plus guidance to look up contact, account, term, and tax code ids first.

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

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

The description states a specific verb and resource: 'WRITE: create a sales invoice for a customer.' It clearly distinguishes creation from sibling read/list tools such as bukku_list_sales_invoices and bukku_get_sales_document.

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

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

It gives clear usage context: status draft vs ready, payment_mode credit/cash dependencies, and when myinvois_action is required. It does not name alternatives or explicitly say when not to use this tool, but the write/create context is clear.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, covering the safety profile. The description adds only the endpoint path and single-record cardinality, with no information about not-found behavior, authentication needs, rate limits, or return contents.

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

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

The description is two short sentences with the purpose front-loaded and no filler. The endpoint path is mildly redundant with the name and annotations, but overall it is appropriately sized for a simple getter.

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

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

For a low-complexity read tool with full schema coverage and clear annotations, the description is adequate but incomplete: it does not mention when to prefer this over bukku_list_accounts or what happens when the id is not found. With no output schema, a brief note on the returned account shape would have helped, though the complexity is low.

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

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

There is one parameter, account_id, and schema description coverage is 100% with the schema stating 'Bukku account id.' The description's 'by id' reinforces the lookup key but adds no format, constraint, or example beyond the schema, so the baseline of 3 applies.

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

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

The description states the resource (ledger account), cardinality (one), and lookup key (id), which implicitly distinguishes it from the sibling bukku_list_accounts. The action verb is carried by the tool name and title rather than the description text, but the purpose remains clear.

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

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

There is no explicit guidance on when to use this tool versus bukku_list_accounts or any other sibling. The only usage cue is the phrase 'by id,' leaving the agent to infer that a known account id is required and that listing is a separate tool.

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

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

Annotations already declare read-only, non-destructive, open-world behavior; the description adds only that the record is returned 'in full' and shows the endpoint path. It does not add auth, rate-limit, error, or return-shape context beyond the annotations.

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

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

Two short fragments, front-loaded with what is returned and the endpoint path. There is no wasted text.

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

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

For a simple two-parameter read tool with full schema coverage and safety annotations, the description covers the resource and scope. It is slightly thin on return format because there is no output schema, but 'in full' provides minimal context.

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

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

Schema coverage is 100%, with the type enum and transaction_id documented in the schema. The description adds the endpoint path mapping categories to URL segments, but does not explain value mapping or id semantics beyond what the schema provides.

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

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

The description identifies a single bank transaction and enumerates the three transaction types, making clear this retrieves one record rather than a list. It is a clear verb+resource implication, but it does not explicitly name list_bank_transactions as the sibling alternative.

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

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

It implies use when retrieving a single transaction by type and id via the endpoint path, but never states when to use it instead of list_bank_transactions or that an id must be obtained first.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the payload contents (persons, addresses, tax/registration numbers, default accounts, credit limit), which is genuinely useful, but says nothing about behavior for a missing or invalid id, or whether the response is a nested object.

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

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

Two short sentences, front-loaded with the payload contents and ending with the endpoint mapping. Every clause carries information; only the field enumeration borders on verbose, and it earns its place since there is no output schema.

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

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

With one fully documented parameter, rich annotations and no output schema, the description usefully summarizes the returned record shape and the underlying endpoint. The only gap an agent might need is error/missing-contact behavior, which is minor for a simple read.

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

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

Schema coverage is 100% for the single contact_id parameter and it is already documented as 'Bukku contact id.' with positivity/range constraints. The description adds no format or sourcing hints (e.g. obtained from bukku_list_contacts) beyond the {id} path template, so baseline 3 applies.

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

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

States a specific verb (implicitly fetch, via the GET endpoint) and resource (a single contact) and enumerates what the record contains, which distinguishes it from the list sibling. It never says outright 'retrieve' but 'One contact with ...' plus the GET path makes the purpose unambiguous.

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

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

The phrase 'One contact' contrasted with bukku_list_contacts is an implicit usage signal, and the endpoint pins it to an id-based fetch. There is no explicit when-to-use/when-not or any mention of the list alternative by name, so guidance remains implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine value by disclosing the return shape (the entry with its debit and credit lines) and the REST path, but says nothing about not-found behavior or line pagination.

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

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

Two sentences, no filler, with the payload content front-loaded before the endpoint reference. Nothing extraneous and nothing needed is buried.

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

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

For a single-parameter read with no output schema, the description gives an adequate picture: one entry, including debit and credit lines, fetched by id. A note on missing-record behavior would close the remaining gap, but the essentials are present.

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

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

Only one parameter and schema description coverage is 100%, so the schema already documents transaction_id as a positive integer Bukku transaction id. The description adds no format, sourcing, or validation detail beyond echoing 'id' in the endpoint path, meriting the baseline.

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

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

States a specific verb and resource ('One journal entry with its debit and credit lines') plus the underlying endpoint GET /journal_entries/{id}, which pins it as a single-record fetch. The singular framing implicitly distinguishes it from bukku_list_journal_entries, but that sibling is never named.

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

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

Usage is only implied: taking a transaction_id makes it obvious this is a by-id lookup, and 'one journal entry' hints at the single-vs-list split. There is no explicit statement of when to prefer this over bukku_list_journal_entries or what to do if the id is unknown.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description's added value is the note that POST /v2/lists is nonetheless a read endpoint, which preempts an agent mistaking the HTTP verb for a mutation. It does not mention batching limits, but that is minor against the annotation coverage.

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

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

Two compact sentences, front-loaded with the resource category before the enumeration and the read-semantics caveat. The long list of values earns its place because it disambiguates the enum names.

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

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

With one required parameter at full schema coverage and no output schema, the description supplies enough to call it correctly. It does not hint at the response shape (presumably an object keyed by list name), which is the only remaining gap for an undocumented return value.

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

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

Schema coverage is 100%, so baseline would be 3, but the prose maps human-readable labels onto terse enum values the schema does not explain (terms = payment terms, fields = custom fields, settings = company settings), which is real added meaning. The one gap is that 'classification_code_list' appears in the enum but is never mentioned or glossed in the description.

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

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

The description names a specific verb and resource and then enumerates exactly which reference lists are returned (tax codes, terms, currencies, settings, etc.), so an agent understands the payload. It does not state how this differs from overlapping siblings like bukku_list_accounts, bukku_list_contact_groups, bukku_list_product_groups or bukku_list_tags, which return many of the same entities.

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

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

"Reference data needed to fill in documents" implies the usage context but does not give explicit when-to-use or when-not-to-use rules. The overlap with the individual bukku_list_* siblings is never addressed, so an agent has no guidance on choosing this batched call over those single-list calls.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value by enumerating the nested payload (units, prices, accounts, tax) and the underlying HTTP route, but says nothing about not-found behavior, permission requirements, or rate limits.

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

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

Two short sentences with no filler — payload composition first, endpoint second. Every clause earns its place and nothing is buried.

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

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

For a simple one-parameter read with annotations covering safety and no output schema, the field enumeration is a useful substitute for a return-value spec. However, the field list is terse and leaves error and permission behavior entirely unaddressed, so it is adequate rather than complete.

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

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

Schema coverage is 100% and the single parameter is documented as 'Bukku product id.' The description's contribution is limited to showing product_id is a path segment via /products/{id}; it adds no format, sourcing, or lookup guidance beyond the schema.

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

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

The description names a specific resource and scope — a single product ('One product') — plus the payload it carries: units, prices, accounts, tax settings. This implicitly separates it from bukku_list_products, but it never names that sibling, so differentiation is inferred rather than stated.

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

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

There is no explicit guidance on when to use this versus bukku_list_products or bukku_get_lookup_lists; the only cue is the endpoint template GET /products/{id}, which implies you must already have an id. No prerequisites, no exclusions, and no mention of what to do if the id is unknown.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the response is the full document including lines, taxes, terms, payments and status, which is useful given there is no output schema, but it says nothing about not-found behavior for a bad id or whether payments/refunds are nested under the parent bill.

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

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

Two compact clauses with zero waste: content scope first, then the endpoint template. Nothing redundant and no filler.

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

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

With no output schema, the description usefully enumerates the returned sections (lines, taxes, terms, payments, status), which is what an agent needs to decide whether one call suffices. The only gap is the absence of error/missing-id behavior for a two-required-param mutating-free lookup.

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

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

Schema coverage is 100%, so both parameters are already documented. The description restates the type enumeration in prose ('a bill, order, goods received note, credit note, payment or refund') and gives the URL pattern /purchases/{type}/{id}, which confirms the two params compose a path but adds no constraint beyond the schema.

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

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

States a specific verb and resource ('One purchase document in full') and enumerates what the document contains, so an agent knows exactly what comes back. It is not explicitly contrasted with its nearest sibling, bukku_get_sales_document, though the 'purchase' framing and type list make the domain clear.

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

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

Usage is only implied: fetch a single document by type and id, as opposed to the list_* siblings. There is no explicit guidance on when to prefer bukku_list_purchase_documents or bukku_list_purchase_bills, and no note that a valid id must first be obtained from a list call.

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

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

The annotations already declare readOnlyHint, non-destructive, and openWorld, so the safety profile is covered. The description adds real behavioral value by specifying the returned payload shape (lines, taxes, terms, payments, status) and the underlying GET route, though it says nothing about auth, pagination, or errors.

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

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

Two compact sentences, front-loaded with purpose and payload contents, ending with the endpoint for orientation. No filler.

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

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

For a two-parameter read tool with full schema coverage and readOnly annotations, the description covers purpose, scope, and roughly what comes back. Slightly short only on how an agent should obtain a valid transaction_id.

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

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

Schema coverage is 100% and the enum already documents every allowed type value, so the schema does the heavy lifting. The description's enumeration of document types mirrors the enum without adding syntax or constraints beyond it, which is the baseline 3 case.

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

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

The description names a specific verb ('Get') and resource ('one sales document in full'), enumerates the concrete document types covered, and lists the data returned (lines, taxes, terms, payments, status). An agent can distinguish it from bukku_list_sales_documents purely on the 'one document in full' scope.

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

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

Usage is implied by the 'one document' phrasing and the required type/id pair, but there is no explicit when-to-use guidance, no prerequisite such as needing an id from the list endpoint first, and no sibling alternative is named.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is fully covered. The description adds only that ids feed invoice lines; it says nothing about pagination, result volume, or default filtering behavior beyond what the is_archived schema field states.

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

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

Three short sentences, front-loaded with the action and scope, with the invoice-line context placed before the endpoint reference. The trailing 'GET /accounts' is mildly redundant but harmless.

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

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

With no output schema, the description does not indicate what an account record contains (id, name, category) or whether results are paginated, which matters for a list tool with zero required parameters. It does supply the downstream-purpose context, which is the most valuable piece.

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

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

Schema coverage is 75%, so search, sort_dir and is_archived are already documented in the schema. The description adds a small amount by mentioning category-based listing (the one enum without a schema description) but gives no semantics for the values or how filters combine.

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

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

States a specific verb and resource ('List ledger accounts from the chart of accounts') and clarifies the scope with 'optionally by category'. The 'list' vs 'get' distinction from sibling bukku_get_account is implied by the name but never stated explicitly, so it falls short of full sibling differentiation.

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

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

The note 'Account ids are used on invoice lines' implies the context in which an agent would call this (to obtain ids for invoice creation), which is genuine usage guidance. However, it never says when to prefer bukku_get_account for a single account, nor that filtering by category or archived state is the way to narrow results.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description's only addition is the transfer-parameter applicability note, which largely restates what the schema already says ('Money in / money out only'). No return shape, pagination behavior, or default-status nuance is disclosed beyond structured fields.

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

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

Two short sentences plus the endpoint path — the transaction-type scope is front-loaded ahead of the parameter caveat, and every clause carries information. No filler or restated title.

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

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

For a read-only filtered list with 11 fully documented parameters, an enum-bound required type, and no output schema, the description covers the essentials. The remaining gap is pagination/return-shape behavior, which the schema partially addresses via next_page on the page parameter.

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

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

Schema description coverage is 100%, with all 11 parameters documented including enums and defaults, so the schema does the heavy lifting and baseline 3 applies. The description reinforces the transfer exclusion for contact_id and sort_by but adds no filtering semantics, date-range behavior, or sort interaction detail beyond the schema.

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

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

States a specific verb (list) and resource (banking transactions), and enumerates the three transaction families it covers (money in, money out, transfers). It maps cleanly onto the GET /banking/{incomes|expenses|transfers} endpoint, so an agent knows this is a collection query and can distinguish it from the singular bukku_get_bank_transaction, though it never names that sibling explicitly.

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

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

It gives one concrete usage constraint — contact_id and sort_by do not apply to transfers — which tells the agent how to shape a transfer query, but it offers no guidance on when to choose this tool over bukku_get_bank_transaction or the account/journal siblings. Usage is implied rather than instructed.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the HTTP endpoint GET /contacts/groups, but does not disclose return format, pagination, or any other behavioral detail beyond the annotations.

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

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

The description is front-loaded and brief, consisting of one useful sentence plus the endpoint. Every element earns its place, with no redundant or filler text.

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

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

For a simple, no-parameter list tool with annotations covering safety, the description is largely complete. It tells the agent that the result contains contact groups whose IDs can be used elsewhere, though it does not describe the exact response shape or pagination behavior.

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

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

The tool has zero parameters, so there are no parameter semantics to explain. The schema is empty and no additional parameter guidance is needed, which matches the baseline of 4 for a no-parameter tool.

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

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

The description gives a specific verb and resource: 'List the contact groups.' It also clarifies the relationship to the sibling bukku_list_contacts by explaining that group IDs are used to filter contacts, which distinguishes this tool from listing contacts directly.

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

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

It provides a clear use case: retrieve contact groups so their IDs can be used to filter bukku_list_contacts. However, it does not state when not to use this tool or explicitly compare it with alternatives such as bukku_list_tags or bukku_list_contacts.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds useful behavioral context by stating it is a GET endpoint and naming the returned fields, though it does not describe pagination or response envelope details.

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

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

The description is short and front-loads the purpose, contact types, and returned fields. The search-matching sentence is useful, though the trailing endpoint reference is marginal but not harmful.

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

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

Given 8 optional parameters, high schema coverage, and rich annotations, the description is reasonably complete for a list tool. It names returned fields and search behavior, while pagination and status defaults are handled by the schema; only alternative-tool guidance is notably absent.

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

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

Schema description coverage is 88%, so the schema already documents nearly all parameters thoroughly, including enums and pagination. The description repeats the search-matching fields but adds little parameter meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description gives a specific verb and resource: list contacts, with the contact types and key return fields named. It is clearly different from create/get/archive tools by being a list operation, but it does not explicitly name sibling alternatives or differentiate from list_contact_groups beyond the resource name.

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

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

The description says what the tool lists and how search matches fields, but gives no explicit guidance on when to use it versus bukku_get_contact or bukku_list_contact_groups. There are no exclusions or selection criteria, so the agent must infer usage from the tool name.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that this is a GET endpoint and specifies 'manual' journal entries, but does not add notable behavioral details such as default status exclusions or pagination expectations beyond what the schema already documents.

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

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

The description is two short elements with no wasted text: a front-loaded statement of what the tool lists and the endpoint. It is appropriately sized for a straightforward list operation.

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

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

For a read-only list tool with complete schema descriptions and clear annotations, the description is largely sufficient. It identifies the resource and filters, though it could have explicitly contrasted this with bukku_get_journal_entry or noted that void entries are excluded by default.

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

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

Schema description coverage is 100%, so all seven parameters are already well documented. The description mentions date, status, and keyword filtering, which aligns with the schema but adds no extra syntax, default, or interaction detail beyond what the schema provides.

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

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

The description gives a specific verb and resource: 'List manual journal entries.' It also names the supported filter axes (date, status, keywords), which makes the tool easy to distinguish from the single-entry sibling bukku_get_journal_entry, though no explicit sibling differentiation is stated.

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

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

The description implies this is the listing/search endpoint for journal entries, which is useful context. However, it does not explicitly say when to use this instead of bukku_get_journal_entry or mention any exclusions, so the routing guidance remains implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing on behavior — no note about pagination, result volume, or whether groups include nested products — so it fails to contribute beyond structured fields.

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

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

Two short fragments, front-loaded with the action and resource, with no filler. The brevity is appropriate for a zero-parameter list call, though the second sentence (HTTP path) earns little place.

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

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

For a simple, no-argument, read-only list tool the definition is minimally sufficient, especially with annotations covering safety. However, with no output schema present, the description could reasonably say what a product group contains or roughly what is returned.

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

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

The tool takes zero parameters, so there is nothing for the description to explain; baseline 4 applies. The appended endpoint path is harmless but not agent-relevant.

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

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

The description names a verb (List) and resource (product groups), but it is essentially a restatement of the title with an HTTP path appended. It offers no scope details (e.g. what a product group is, whether results are paginated) and does not distinguish it from siblings like bukku_list_products or bukku_get_product.

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

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

There is no guidance on when to use this tool versus the closely related bukku_list_products, bukku_get_product, or bukku_list_tags. An agent must infer the distinction from the name alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is clear. The description adds some useful context by naming the endpoint and the kinds of product data returned, but it does not describe pagination behavior, default filtering, or result shape beyond the field categories.

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

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

The description is a single compact sentence followed by the endpoint, with no wasted wording. The main purpose is front-loaded and immediately usable.

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

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

Given seven optional parameters with strong schema coverage and annotations covering the safety profile, the description supplies enough context for selection and invocation. The lack of an output schema is partly offset by naming the included product details, though return structure and pagination semantics remain lightly covered.

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

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

Schema description coverage is high at 86%, so the schema already documents nearly all parameter meanings, including paging, search, mode, type, sorting, and archived inclusion. The description adds no parameter-specific semantics beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: lists products and bundles, and notes the returned categories of information (sales/purchase details, SKU, stock). It does not explicitly distinguish this list operation from sibling tools like bukku_get_product or bukku_list_product_groups, but the purpose is otherwise unmistakable.

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

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

The description gives no explicit guidance on when to use this tool instead of bukku_get_product, bukku_list_product_groups, or other related tools. Usage is only implied by the name and the word 'List'; there are no alternatives or exclusions named.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the resource shape and endpoint but says nothing about pagination behaviour, default ordering or result volume, which matters for a 10-param list tool.

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

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

Two sentences, the returned fields front-loaded and the filter options and endpoint following. No wasted text, though the endpoint fragment could be dropped without loss.

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

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

For a filter-driven list tool with no required parameters and no output schema, naming the returned fields covers the main missing piece. Pagination and default ordering are handled by the schema descriptions, so the definition is close to sufficient.

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

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

Schema coverage is 70%, so most parameters are documented in the schema. The description's mention of payment status values adds little because those enums are already in the schema, and it does not clarify the two distinct status concepts or the sort parameters.

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

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

The description states a specific verb and resource ('List purchase bills'), names the returned fields (number, date, supplier, amount, balance, payment status) and the endpoint. It does not distinguish itself from the close sibling bukku_list_purchase_documents, which is the main remaining gap.

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

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

It lists the available filter dimensions (date, supplier, payment status, keywords), which implies how to narrow results. But it never says when to prefer this over bukku_list_purchase_documents or bukku_get_purchase_document, nor does it state any prerequisites.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety behavior is covered. The description adds the payment_status applicability constraint, but that is also present in the schema's payment_status description. Endpoint routing is not behaviorally important for the agent.

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

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

The description is front-loaded and efficient: it states what is listed, then the sibling exclusion, then the payment_status constraint. The trailing HTTP endpoint adds minimal value for most agents but does not distract significantly.

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

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

For a 10-parameter read-only list tool with annotations and detailed schema descriptions, this description covers the essential scope and the main sibling boundary. It lacks return-value or pagination hints, but no output schema exists and the schema already documents pagination parameters, so the omission is minor.

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

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

Schema description coverage is 90%, so the schema already documents parameter meaning, enums, defaults, and constraints. The description adds no parameter semantics beyond what the schema provides; its payment_status note is duplicated in the schema description.

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

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

The description gives a specific verb (List) and enumerates the exact resource types covered: purchase orders, goods received notes, supplier credit notes, supplier payments, refunds. It explicitly distinguishes itself from the sibling bukku_list_purchase_bills by noting bills have their own tool.

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

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

It routes the agent away from this tool for bills ('bills have their own tool, bukku_list_purchase_bills'), which is a clear alternative boundary. It also clarifies that payment_status only applies to certain document types. However, it does not say when to use get_purchase_document versus this list tool, leaving a small gap in selection guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds the concrete endpoint mapping and the payment_status applicability constraint, which is genuine extra context, but says nothing about pagination, result volume, or sort defaults. With annotations shouldering the behavioral load, this is adequate but thin.

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

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

Two compact sentences: the resource enumeration comes first, then the invoice carve-out, then the filter constraint and endpoint. No filler, and the most decision-relevant information (which types, which sibling) is front-loaded.

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

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

Ten parameters with only one required, and the description correctly focuses on the tool's only real ambiguity: which document type and how it splits from the invoice tool. With 90% schema coverage and no output schema, the remaining gaps (return shape, ordering defaults) are minor, though it doesn't hint at what a list reply contains.

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

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

Schema coverage is 90%, so nearly every parameter is self-documented, establishing a baseline of 3. The description restates payment_status scope, which the schema already states, and adds no filtering semantics for search, status default, or date range beyond what the schema provides. No added value over structured fields.

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

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

States a specific verb (list) and enumerates exactly which resources are covered (quotes, orders, delivery_orders, credit_notes, payments, refunds), and explicitly carves out invoices as belonging to the sibling bukku_list_sales_invoices. An agent can distinguish this from bukku_list_sales_invoices and bukku_get_sales_document without opening a schema.

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

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

Names the alternative tool for invoices explicitly and states the routing condition (invoices have their own tool). It also scopes payment_status to only credit notes, payments and refunds, telling the agent when not to pass that filter. A clear when/when-not/alternative set for a list tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the endpoint path and the returned fields, which is useful, but it omits pagination behavior, default status exclusion of void, and page-size defaults that matter for a list endpoint.

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

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

Three short sentences, each earning its place: returned fields first, filter dimensions second, endpoint third. No redundancy or filler.

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

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

For an 11-parameter list endpoint with no output schema, the description gives the agent the core picture: what is returned, how to filter, and the underlying endpoint. It could mention pagination and sorting more clearly, but the schema covers those details adequately.

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

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

With 73% schema coverage and 11 parameters, the schema already documents most filters in detail. The description reinforces date, customer, payment_status and search filtering but adds no syntax or behavioral nuance, and leaves status, sort_by, sort_dir, page, page_size and payment_mode to the schema.

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

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

States a specific verb and resource ('List sales invoices') and enumerates the returned fields, so an agent knows exactly what this returns. It does not explicitly distinguish itself from the sibling bukku_list_sales_documents, which is the only missing clarity element.

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

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

The description implies usage by listing filter dimensions (date, customer, payment status, keywords), which tells an agent how to narrow results. However, it never says when to choose this over bukku_list_sales_documents or bukku_get_sales_document, and gives no exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the API route (GET /tags) but nothing about freshness, pagination, or whether the tag set is account-wide or workspace-scoped.

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

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

Two short sentences with the purpose front-loaded. The trailing 'GET /tags' is mildly redundant with the name but is cheap and confirms the underlying endpoint.

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

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

There is no output schema, so the description is the only place an agent could learn the return shape (e.g., id/name fields per tag), and it does not say. For a trivial zero-param read the gap is small but real.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; schema coverage is 100% over an empty object. Baseline for a no-argument tool applies.

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

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

States a specific verb (List) and resource (tags/labels on transactions), and clarifies in parentheses what a tag is. It is distinguishable from the sibling list_* tools by resource, though it never mentions overlap with bukku_get_lookup_lists.

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

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

Usage is implied: call this to discover which labels may be applied to transactions. There is no explicit when-to-use/when-not guidance and no mention of bukku_get_lookup_lists, which plausibly overlaps as a discovery endpoint.

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

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

Adds meaningful context beyond the annotations: archiving is non-destructive in the sense that nothing is deleted and the contact only disappears from active lists. Combined with idempotentHint and destructiveHint=false, the agent has a clear behavioral picture; only the response/return shape is unspecified.

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

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

Three terse sentences, front-loaded with the write intent and the mode mapping, with zero redundant filler.

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

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

For a trivial two-parameter, fully documented tool with rich annotations, this is nearly complete. The only gap is what the call returns, which is a minor omission absent an output schema.

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

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

Schema coverage is 100% and both parameters are self-documented, so the schema already does the work. The description's 'is_archived true / false' mapping duplicates the schema description rather than adding new semantics, warranting the baseline 3.

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

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

States a specific verb and mode ('WRITE: archive ... or restore'), names the resource (contact), and gives the endpoint (PATCH /contacts/{id}). It is unambiguously distinct from siblings like bukku_create_contact or bukku_get_contact.

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

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

Explains the effect of archiving ('hides it from active lists; nothing is deleted'), which tells the agent when this is appropriate versus deleting. No explicit alternatives or exclusion conditions are named, 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.