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

Annotations indicate destructiveHint=true, and the description elaborates on destructive actions (e.g., tax delete is permanent) and non-destructive ones. Also mentions API scope requirements for journal. No contradictions with 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?

Description is front-loaded with purpose and then enumerates combinations efficiently. While detailed, each sentence adds value. Could be slightly more concise but well-organized.

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

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

Given the tool's complexity (13 parameters, nested objects, multiple resources), the description covers most aspects including pagination, optional filters, and return behavior for create. No output schema exists, but the description compensates with behavioral notes.

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%, but description adds value by explaining searchable fields for accounts and calendar_years, the effect of creating a future calendar year, and the meaning of payload fields. This goes beyond the schema definitions.

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

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

The description clearly states the tool's purpose: accessing the bexio accounting foundation with specific sub-resources. It lists all valid resource/action combinations, distinguishing it from sibling tools like bexio_invoices or bexio_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?

Provides explicit instructions for each resource and action, including required parameters like search_criteria for search actions and optional filters for taxes and journal. Lacks explicit when-not-to-use guidance but is otherwise 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?

Description discloses that delete is 'destructive, cannot be undone', which aligns with the destructiveHint annotation (true). It also specifies that create requires at least the name field. No contradictions with 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?

Description is a single coherent paragraph that front-loads the main purpose and uses semicolons to separate action details. It is concise and without filler, though formatting could be more structured with bullet points.

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

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

Covers all actions, required parameters, and constraints (e.g., limit/offset for list, search fields). Lacks examples of payload or return values, but output schema is absent. Adequate for a multi-action CRUD tool.

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

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

Schema covers all 8 parameters with descriptions (100% coverage). The description adds some context by summarizing actions and listing searchable fields, but does not significantly enhance understanding 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?

Description clearly states it manages additional addresses of a contact, enumerates six specific actions with their required parameters, and differentiates from sibling tools (e.g., bexio_contacts) by focusing on a specific sub-resource.

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?

Description provides clear context by listing each action's prerequisites (e.g., contact_id required for all actions) and mentions searchable fields for the search action. However, it does not explicitly state when not to use this tool or suggest alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, making safety clear. The description adds that it is 'Read-only' (redundant) and describes the two actions, but does not disclose additional behavioral traits like rate limits, caching, or whether results are paginated beyond the schema's limit/offset. No contradictions with 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 concise (2 sentences) and front-loaded with the tool's primary purpose. Every sentence adds value: the first defines the read operation and fields, the second clarifies actions and parameter roles. No unnecessary words.

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?

Despite lacking an output schema, the description lists the fields returned (name, owner, IBAN, etc.) and specifies the two actions with required parameters. For a read-only tool with full schema coverage and safety annotations, this is sufficient 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.

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

Schema coverage is 100% with all parameters described. The description reiterates the action enum and adds minor context ('optional limit/offset', 'numeric id'), but does not add significant meaning beyond what the schema already provides. 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 clearly states 'Read bank accounts configured in bexio' and lists specific fields (name, owner, IBAN, etc.). It explicitly defines the two actions 'list' and 'get' with parameter roles, effectively distinguishing this tool from siblings like bexio_accounting or bexio_banking_payments.

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 purpose ('read bank accounts'), but the description provides no explicit guidance on when to use this tool over alternatives (e.g., bexio_accounting, bexio_banking_payments). There are no when-not-to-use or exclusion criteria, leaving the agent to infer context from the 34 sibling tool names.

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 description adds important behavioral details beyond annotations: cancel and delete cannot be undone, update has restrictions on mutable fields, create requires specific payload. This complements the destructiveHint and readOnlyHint annotations well.

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

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

The description is moderately concise, organized by action in a single paragraph. It front-loads the purpose and then details each action. Could be improved with bullet points or clearer separation, but not overly verbose.

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 no output schema, the description provides reasonable context for each action's behavior and constraints. It mentions that payment ids are strings (uuid or numeric). However, it does not describe the response format for list/get, which might be needed for integration.

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 100% schema coverage, baseline is 3. The description adds value by explaining that certain fields (account_id, type, purchase_reference) are create-only and ignored on update, which is not in the schema descriptions. This helps agents avoid invalid update requests.

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

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

The description clearly states it manages outgoing bank payments with specific actions (list, get, create, update, cancel, delete). However, it does not explicitly differentiate from sibling tools like bexio_outgoing_payments, relying on the tool name and context.

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

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

The description provides clear conditions for each action: update only open payments with certain immutable fields, cancel/delete are irreversible, create requires specific fields. It does not compare to alternative tools but within the tool it gives actionable 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 indicate destructiveHint=true; description adds that delete is permanent and cannot be undone. Also details payload requirements for create/update. No contradiction; provides additional behavioral context beyond 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?

Efficiently structured by action with front-loaded purpose. Every sentence adds specific and necessary information for tool usage. No redundancy or irrelevant details despite the complexity.

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

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

Covers all actions, required vs optional parameters, conditional logic, constraints (e.g., character limits, enum values). With high param count and nested objects, the description leaves little ambiguity. No output schema but acceptable given action descriptions suffice.

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% but description adds value beyond field descriptions by explaining conditional logic (e.g., provide amount_man when manual_amount=true, amount_calc otherwise) and grouping constraints per action. Reduces ambiguity for complex scenarios.

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?

Clearly states it manages purchase bills/supplier invoices (accounts payable, bexio purchase 4.0 API). Specifies resource type and differentiates from sibling tools like bexio_invoices (sales invoices).

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

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

Describes each action (list, get, create, update, delete, etc.) and their inputs, but does not explicitly guide when to choose this tool over alternatives or when not to use it. Implicit context from purpose but no explicit usage 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, idempotentHint, openWorldHint, and destructiveHint false. The description adds transparency by listing the specific fields returned (name, legal form, address, etc.) and the available actions. This provides behavioral 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?

The description is concise, front-loaded with the primary purpose, and every sentence adds value. No redundant or filler content.

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

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

Given the tool's simplicity (2 parameters, two actions), the description, combined with annotations, provides nearly complete context. It lists return fields and actions. No output schema exists, but the description compensates by listing the data. Minor omission: no mention of error conditions or pagination for 'list', but these are minor for this tool.

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

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

Schema coverage is 100% with both parameters described. The description repeats the action names and the id requirement but adds no new semantic meaning beyond what the schema already provides. Baseline score of 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 clearly states the tool reads the company profile, lists the specific data fields it returns, and defines the two actions ('list' and 'get'). This is a specific verb+resource combination that distinguishes it from the many sibling tools.

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

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

The description provides clear context for when to use the tool (to read company profile data). It does not explicitly state when not to use it or mention alternatives, but given the sibling tools cover different domains, the usage is implied. A small deduction for lack of exclusion 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 indicate destructiveHint=true; the description reinforces this by stating delete is 'destructive, cannot be undone'. It also describes payload requirements for create/update. No contradictions found.

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

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

The description is compact but packs dense information into one paragraph. It could benefit from bullet or action-specific structuring for easier scanning, but it remains efficient without excess words.

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 7 parameters, nested objects, and no output schema, the description covers all essential aspects: pagination, sorting, search fields, payload requirements, and destructive behavior. It fully equips an agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description adds value by providing examples for order_by (e.g., 'id_desc'), clarifying searchable fields for search, and noting partial behavior for payload on update.

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

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

The description clearly states the tool manages contact groups and lists all specific actions (list, search, get, create, update, delete). It distinguishes from sibling tools by focusing on contact groups and referencing their role as categories assigned via contact_group_ids.

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

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

The description provides explicit context for each action, including required and optional parameters (e.g., limit, offset for list; search_criteria for search). It does not explicitly compare with sibling tools, but the tool name and specificity make usage clear.

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

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

Annotations already indicate destructiveHint=true, and the description explicitly warns for delete: 'destructive, cannot be undone'. It also details the behavior for search (AND logic, default 'like' operator) and list (pagination, ordering). No contradictions. However, it does not discuss authorization or rate limits, but given the annotations cover the safety profile, the added context is valuable.

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, dense paragraph that front-loads the purpose and efficiently covers all actions without redundancy. Every sentence adds value. It could benefit from minor structuring (e.g., bullet lists), but as prose it is very concise and effective.

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 CRUD tool with 7 parameters, no output schema, and 100% schema coverage, the description is remarkably complete. It explains the relation concept, all CRUD actions, pagination hints, search behavior, and required fields. The only missing part is explicit return format, but since there is no output schema, the description cannot be blamed. It leaves no major gaps.

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

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

The input schema has 100% coverage (context signals), and the description adds substantial meaning: example of linking person to company, clarification of required payload fields for create, listing searchable fields, explaining order_by suffix '_desc', and describing search criteria structure. This goes well beyond the schema's basic descriptions.

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 starts with a clear statement: 'Manage relations between two contacts (e.g. link a person to their company)'. It then enumerates all actions (list, search, get, create, update, delete) and their specifics. This is a specific verb+resource description that clearly distinguishes this tool from other bexio tools, which are for different 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?

The description provides context for each action, such as required vs optional parameters for list, search, create, etc. It does not explicitly state when to not use this tool or mention alternatives, but the actions are self-contained and the tool's domain (contact relations) is clear. A small gap is the lack of explicit when-not-to-use 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?

The description adds context beyond annotations by noting that delete permanently removes contacts (cannot be undone) but can be restored shortly afterward, and that get includes base64 profile_image. Annotations already indicate destructiveHint true, so the description enhances transparency.

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 well-structured, listing each action with its parameters and constraints. It is somewhat lengthy but organized, making it easy to scan. Every sentence adds 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?

Given the complexity of the tool (multiple actions, nested objects, search criteria), the description covers all essential aspects: actions, required fields, searchable fields, deletion behavior, pagination, and deprecation notes. It leaves no major gaps.

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

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

With 100% schema coverage, the descriptions already document parameters. The tool description adds value by explaining searchable fields, required fields for create/bulk_create, and deprecation of the address field, which aids effective parameter use.

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

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

The description clearly states the tool manages bexio contacts, identifies it as the central address book referenced by quotes, orders, invoices, and projects, and lists all supported actions (list, search, get, create, update, delete, bulk_create, restore). This specificity distinguishes it from sibling tools.

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

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

The description implies usage for contact management and highlights that it is the central address book, providing context. However, it does not explicitly state when to use this tool versus alternatives or when not to use certain actions.

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 confirm read-only and idempotent behavior. The description adds concrete behavioral details: actions, optional parameters, searchable fields, and the relationship to contacts via contact_branch_ids. No contradictions with 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 extremely concise, packing purpose, actions, and parameter details into a single sentence plus a compact list. Every phrase adds value without redundancy.

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

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

Despite lacking an output schema, the description fully covers the tool's functionality: read-only master data retrieval with two actions, pagination, ordering, and search. It is complete for the task.

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%, but the description adds critical context beyond the schema: for 'list', it specifies valid order_by values (id, name) and the format for descending; for 'search', it states required search_criteria and searchable field 'name'. This enriches the parameter understanding.

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

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

The description clearly states 'Read contact sectors' and specifies actions (list, search), making the tool's purpose unambiguous. It distinguishes itself from sibling tools by focusing on a specific entity referenced by 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 description indicates the tool is read-only and outlines when to use list vs search, providing implicit usage guidance. However, it does not explicitly compare with alternative tools or specify when not to use it.

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

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

Discloses beyond annotations: delete is permanent and cannot be undone; update is PATCH only changes round_factor. This aligns with destructiveHint=true and adds critical 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.

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

Description is a single paragraph but efficiently covers all actions and parameters. Slightly dense; could benefit from bullet points for readability, but no unnecessary content.

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

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

Covers all 7 parameters, schema descriptions present, annotations provide destructive hint. No output schema needed; description adequately explains each action's behavior and required inputs.

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 3. Description adds value by explaining embed example ('exchange_rate'), date format ISO 8601, limit max 2000, and payload examples ('CHF', 0.05).

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

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

The description clearly states the tool manages currencies and reads exchange rates, listing specific actions (list, get, create, update, delete, list_codes, list_exchange_rates) that distinguish it from other bexio sibling tools.

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

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

Each action has context (e.g., list with optional parameters, update only round_factor, delete permanent). However, no explicit when-not-to-use or comparison to alternatives, though none exist for this resource.

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 indicate readOnlyHint=false and destructiveHint=false. The description adds transparency by detailing that issue finalizes the delivery note and adjusts stock when stock management is active, and mentions status codes for draft vs done. This goes beyond 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 concise: two sentences and a structured list of actions. It is front-loaded with purpose and immediately provides actionable details. No superfluous 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?

Without an output schema, the description adequately covers the three actions and their parameters. It mentions that get includes positions and issue adjusts stock. However, details about response format or pagination defaults are missing, but overall sufficient for an agent to use the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining which actions require the id parameter, listing valid order_by fields, and clarifying the effect of issue. This context enriches the schema definitions.

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

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

The description clearly states the tool reads and issues delivery notes, and specifies three actions. It distinguishes from sibling tools by mentioning that deliveries are created from orders via bexio_orders, but does not explicitly differentiate from other related tools like bexio_stock.

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

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

The description explains when to use each action (list, get, issue) and provides context such as optional parameters and the effect of issue. It refers to bexio_orders for creation, giving guidance on alternatives, but does not explicitly state when not to use certain actions.

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 description adds behavioral details beyond annotations, such as the immutability of comments (no edit/delete) and the effect of is_public on comment visibility. Annotations already indicate not read-only and not destructive, which is consistent.

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 paragraph that efficiently conveys the tool's purpose, actions, and key constraints without extraneous information. It is front-loaded with the resource type and action summary.

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?

The description covers all actions, required parameters, and constraints, but does not describe the return format or content of list/get responses. Since there is no output schema, this omission slightly reduces completeness for an agent.

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 100% schema description coverage, the description goes further by grouping parameters per action (e.g., limit/offset for list, comment_id for get, payload fields for create) and explaining the purpose of is_public. This adds context 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 clearly identifies the tool as managing comments on specific sales documents (quotes, orders, invoices) and lists the three actions (list, get, create). It distinguishes itself from general notes by specifying the document types and action constraints.

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

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

The description provides clear usage context by stating that all actions require document_type and document_id, and explicitly notes that comments cannot be edited or deleted via the API. However, it does not mention alternative tools or when to prefer this tool over siblings like bexio_notes.

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?

Discloses that delete is permanent and irreversible, consistent with destructiveHint annotation. Adds details on field applicability and value format (max 6 decimals). No contradictions with 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?

Description is dense but well-organized: first sentence defines scope, then enumerates position types and their fields, then actions, then additional notes. It efficiently packs information without redundancy, though length is justified by complexity.

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

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

Given the tool's complexity (8 params, 7 position types, 5 actions), the description covers most aspects: actions, field mappings, constraints, and pagination. No output schema, but missing return structure is acceptable for a CRUD tool. Slight gap: no response example.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by mapping fields to each position_type, explaining special behaviors (is_optional, is_percentual), and providing format constraints (max 6 decimals). This goes beyond the schema alone.

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?

Clearly states 'Manage line-item positions on sales documents' and enumerates specific document types and position types. Distinguishes itself from sibling tools by focusing on document positions.

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 each action (list, get, create, update, delete) and required parameters. Provides context on which fields apply to which position_type and notes limitations like is_optional only on quotes/orders. Does not explicitly state when not to use but offers sufficient 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?

The description explicitly states 'Read-only', consistent with annotations (readOnlyHint=true). It goes beyond annotations by detailing the output fields for each action, such as numbering format, default currency, and template details, providing full 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.

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

The description is concise and well-structured: a purpose statement followed by a bullet-like enumeration of actions with relevant details. Every sentence adds value without redundancy.

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

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

Given the absence of an output schema, the description adequately covers return values for both actions, listing key fields. It does not mention error handling or pagination, but for a read-only configuration tool, this is 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 100%, baseline 3. The description adds meaning by explaining the order_by syntax (append '_desc' for descending) and clarifies that it applies only to 'list_settings'. It also describes the action enum values in detail.

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

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

The description clearly states 'Read sales-document configuration' and lists two specific actions ('list_settings' and 'list_templates') with detailed output fields. It distinguishes from sibling tools like bexio_invoices, which deal with actual documents, by focusing on configuration and templates.

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

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

The description provides clear context for when to use this tool (to read configuration) but does not explicitly state when not to use it or mention alternatives. The sibling tools imply other purposes, but no direct exclusions are given.

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

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

Annotations include destructiveHint=true and readOnlyHint=false. The description adds value by noting that delete 'permanently deletes the expense — cannot be undone' and that update 'sends the full expense (fields left out are cleared)'. These specifics go beyond the annotations and clarify behavioral traits.

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 paragraph that is moderately concise but could be more structured (e.g., bullet points for actions). It front-loads the overall purpose but becomes dense. Every sentence adds value, but readability could be improved.

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

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

No output schema is provided, and the description omits details on return values, error handling, or authentication requirements. For a tool with 11 parameters, nested objects, and multiple actions, the description is incomplete for an AI agent to reliably invoke without additional context.

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

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

Schema description coverage is 100% with detailed parameter descriptions. The description adds some context (e.g., UUID ids, required fields for create/update, full payload behavior), but does not significantly enhance meaning beyond the schema. 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 clearly states it manages expenses via the bexio 4.0 API, listing multiple specific actions (list, get, create, update, delete, etc.) with brief explanations. This distinguishes it from sibling tools like bexio_bills or bexio_invoices, which cover different domains.

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

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

The description provides action-specific parameter requirements (e.g., list uses pagination/filters, create requires payload with specified fields), offering some guidance. However, it does not explicitly state when to use this tool vs alternatives, nor does it provide exclusions or comparative context with sibling tools.

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 set destructiveHint=true and the description reinforces that delete 'cannot be undone'. It discloses upload alternatives (file_path or content_base64 + file_name), and download/preview return base64 or write to save_path. While no rate limits or auth details are given, the key behavioral traits are covered beyond 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 dense but well-organized with a general statement followed by per-action details in quotes. It front-loads the action list and uses concise language. While long, every sentence adds value, and the structure aids scanning.

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 12 parameters and nested objects, the description covers all actions' required inputs (e.g., id for get/download/preview/usage/update/delete) and upload alternatives. It explains search criteria format and archived_state options. The lack of output schema is acceptable as operations are clear. Slightly more detail on pagination or error handling would raise the score.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining which parameters belong to which actions (e.g., order_by only for list, search_criteria for search), listing searchable fields, and noting that file_name overrides basename for upload. This goes beyond just listing parameter types.

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

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

The description clearly states it manages files stored in bexio, enumerates all actions (list, search, get, download, preview, usage, upload, update, delete), and distinguishes itself from sibling tools by focusing on file operations.

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 lists required and optional parameters per action (e.g., id for get/download/preview, search_criteria for search). It explains when to use list vs search (list returns all files, search filters with criteria). However, it does not explicitly exclude non-file tasks or compare with alternative tools, but sibling tool names indicate clear domain separation.

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 set destructiveHint=true. The description reinforces this by stating that delete 'permanently deletes the payment — cannot be undone.' It also discloses required fields for create, adding context beyond annotations. No contradiction with 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?

Description is a single paragraph that front-loads the general requirement (invoice_id) and then enumerates each action with its specific parameters. Every sentence adds value; no fluff or repetition.

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

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

Given the tool's complexity (6 params, nested objects, no output schema), the description covers all actions and their required/optional fields. It lacks detail on return formats (e.g., for list/get), but the schema fills in some of that. Overall, quite complete for a multi-action tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by grouping parameters per action and explaining required conditions (e.g., 'set either bank_account_id or payment_service_id (1 = PayPal, ...)'). This clarifies usage beyond the schema's individual descriptions.

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?

Description clearly states 'Manage payments recorded on a bexio invoice' and lists four specific actions (list, get, create, delete). This distinguishes it from sibling tools like bexio_banking_payments or bexio_invoices, making 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?

Description specifies that all actions require invoice_id and provides action-specific requirements (e.g., create requires value and either bank_account_id or payment_service_id with enumerated values). It does not explicitly mention when not to use this tool versus alternatives, but the context is clear enough.

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 indicate destructiveHint=true and idempotentHint=false. The description adds behavioral context: 'delete permanently deletes the reminder — cannot be undone' and 'create creates the next reminder level' (non-idempotent). Also clarifies email format constraints. No contradictions with 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 a single dense paragraph but front-loaded with the purpose and structured by actions. Every sentence adds value. Could be slightly more scannable with bullet points, but still concise given the breadth of actions (9 actions covered).

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

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

With 7 parameters including nested objects and no output schema, the description covers all actions thoroughly. It explains required and optional parameters per action, searchable fields, and side effects (permanent deletion). Minor omission: does not describe return format for list/search/get (though intuitive for invoice reminders).

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%, but the description adds meaning beyond schema definitions. For 'search', it lists searchable fields (title, reminder_level, etc.). For 'pdf', it explains logopaper and save_path. For 'send', it details the email object structure and required placeholder. This provides actionable guidance.

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

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

The description clearly states it manages payment reminders of a bexio invoice and enumerates all actions (list, search, get, create, delete, send, etc.). The verb 'Manage' plus resource 'payment reminders' distinguishes it from sibling tools like bexio_invoices or bexio_invoice_payments.

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 specifies that all actions require invoice_id and gives per-action parameter requirements (e.g., reminder_id for get/delete/send, email for send). It also includes constraints like 'message must contain [Network Link]' for send, but does not explicitly compare to alternatives or state 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.

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

The description discloses critical behaviors beyond annotations: 'delete' is irreversible, 'cancel' has no un-cancel API, 'issue' transitions draft to pending, positions cannot be updated via 'update', and send requires '[Network Link]' in the message. These details are not captured by annotations (destructiveHint=true, readOnlyHint=false) and greatly enhance transparency.

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 relatively long but well-structured: it starts with the overall purpose and status IDs, then lists each action with its behavior and parameters. Each sentence adds necessary information; no redundancy. Could be slightly more concise by grouping related actions, but the clarity and completeness justify the length.

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

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

Given the tool's complexity (11 parameters, nested objects, polymorphic positions, 13 actions) and no output schema, the description covers most essential aspects: action purposes, parameter constraints, and some return values (e.g., 'get' returns invoice with positions, 'pdf' returns base64 or file). Missing details on error handling and response formats for other actions, but sufficient for safe invocation.

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

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

Schema coverage is 100% and schema descriptions are detailed, but the description adds context such as: the polymorphic positions array supports six types (custom, article, text, subtotal, pagebreak, discount), searchable fields are listed, and pdf action parameters (logopaper, save_path) are explained. This goes beyond the schema's property descriptions.

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 'Manage bexio invoices (kb_invoice)' and enumerates 13 distinct actions (list, search, get, create, update, etc.), each with specific behavior. It clearly distinguishes this tool from siblings like bexio_bills or bexio_quotes by focusing on invoice-specific status IDs and actions.

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?

While there is no explicit comparison to sibling tools, the description provides clear context for when to use each action (e.g., 'list' returns all invoices, 'search' requires criteria). It also includes constraints like the trial period limitation for 'send'. However, it does not discuss prerequisites or alternative tools for similar operations.

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 indicate destructiveHint=true (delete permanent) and readOnlyHint=false. The description adds that delete cannot be undone, and explains search behavior (AND-combined, default 'like' operator). It does not explicitly state that list/get are read-only, but that is implied by the action names. The openWorldHint is not contradicted.

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 well-structured: starts with overall purpose, then lists actions in parentheses with key details. It is front-loaded and each sentence serves a purpose. However, it is somewhat lengthy and could be more concise by removing some redundant parameter details that are already in the schema.

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

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

Given the tool's complexity (6 actions, 7 parameters, nested payload), the description covers all actions, mandatory fields, and key constraints. It does not mention pagination defaults (e.g., limit default 500) or scope requirements for stock (is_stock needs stock_edit scope), which are in the schema but not in the description. No output schema, so return value explanation is not expected.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by specifying that order_by only accepts 'id' or 'intern_name' (with optional '_desc' suffix), which is not in the schema. It also clarifies that search_criteria uses AND logic and default 'like' operator, which is partially in the schema but reinforced.

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

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

The description clearly states the tool manages items/products (articles) and lists all six actions (list, search, get, create, update, delete) with specific detail. It distinguishes from siblings by being the only tool for item CRUD; no overlap with bexio_stock or others.

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?

Each action is explained with when to use it (e.g., list uses limit/offset/order_by, search requires search_criteria with AND logic, create needs intern_name and article_type_id for product/service). However, no explicit comparison to sibling tools (e.g., bexio_stock) is provided, leaving some ambiguity about alternative tools.

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 description discloses key behaviors: delete is permanent, update is a full PUT replacement, file uploads have size (12MB) and format limits, and the scope differentiation for file actions (entry_id vs compound entry). These complement the annotations (destructiveHint true, readOnlyHint false) without contradiction.

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 relatively long but well-structured by action, with clear grouping of entry and file operations. It front-loads the overall purpose. While verbose, the complexity of 9 actions justifies the length; every sentence contributes useful 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?

The description covers all actions, explains return behavior (e.g., file content vs inline base64), and details file upload constraints. It lacks explicit return schemas for list/create/update but compensates with behavioral notes. For a complex tool with no output schema, it is adequately 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% with descriptive fields, so baseline is 3. The description adds value by explaining the 'type' enum meanings (single, compound, group), the update requirement to send full payload, and the entry_id scope for files. This provides meaningful context beyond the schema alone.

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

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

The description clearly states the tool manages manual accounting entries and their attached files, listing all 9 actions with specific verbs (list, create, update, delete, get file, etc.). It distinguishes entry-level vs file-level operations and mentions the API version, providing precise purpose.

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

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

The description explains when to use entry_id vs not for file actions, and notes that locked entries cannot be edited. However, it does not explicitly compare this tool to sibling tools like bexio_bills or bexio_accounting, which handle similar accounting data. The domain is implicit from the title and scope.

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

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

Discloses that delete is permanent ('cannot be undone'), matches annotations (destructiveHint: true). Also notes read-only resources. Adds value beyond annotations by detailing ordering behavior and search constraints. No contradiction.

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?

Well-organized with bullet-like lists for resources and actions, but somewhat lengthy due to comprehensive detail. Front-loaded with purpose and resource overview. Nearly every sentence adds value, though could be slightly trimmed.

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

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

Given the complexity (8 parameters, nested objects, no output schema), the description covers all necessary aspects: action rules, payload shapes, search criteria, ordering, pagination. Complete enough for an AI to use correctly.

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

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

Schema coverage is 100%, but description adds substantial extra meaning: per-resource payload shapes, which fields are required on create, which resources support order_by and which fields, searchable fields per resource. Greatly enhances parameter understanding.

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?

Clearly states the tool manages 'small bexio master-data lookup resources' and lists all resources and actions. Distinguishes from sibling tools by focusing on master data rather than accounting, contacts, invoices, etc.

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?

Provides detailed guidance on which resources support which actions (e.g., 'languages, payment_types, communication_types — list, search only'), explains ordering options per resource, and searchable fields. Lacks explicit when-not-to-use or alternatives but the context is clear from the resource list.

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 description goes beyond annotations by detailing the permanence of delete ('cannot be undone') and noting that search returns results based on criteria. Annotations already indicate destructiveHint=true, readOnlyHint=false, and idempotentHint=false. No contradictions exist.

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 with the overall purpose and action list. Each sentence adds necessary detail. It could be slightly tighter but remains well-structured and informative without redundancy.

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

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

Given no output schema, the description covers all actions and their parameter requirements. It explains pagination (limit/offset) and search criteria structure. It could mention return format, but the action names imply expected outputs (list returns array, get returns object).

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%, baseline 3. The description adds value by grouping required fields per action (e.g., 'Required on create: user_id, event_start, subject') and listing searchable fields for the search action. This provides meaning beyond the schema's individual field descriptions.

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

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

The description clearly states it manages notes in bexio and enumerates six specific actions (list, search, get, create, update, delete). It distinguishes notes as 'short annotations linked to a user and optionally a contact, project or module entry', which differentiates it from other bexio entity tools.

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

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

The description provides explicit parameter requirements per action (e.g., 'id required for get/update/delete', 'payload required on create: user_id, event_start, subject'). It warns that delete is permanent. While it doesn't explicitly exclude alternatives, the action list and sibling tool names provide sufficient context.

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 annotations (destructiveHint=true), the description warns about irreversible actions ('cannot be undone' for delete and delete_repetition) and mentions limitations (positions cannot be updated). This adds valuable 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.

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

The description is comprehensive but somewhat lengthy, listing all actions with details. While structured and front-loaded, some redundancy exists (e.g., repeating 'cannot be undone'). Could be trimmed for brevity.

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

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

Given the tool's complexity (11 parameters, nested objects, no output schema), the description covers key constraints, action-specific notes, and edge cases. It is sufficiently complete for an agent to use correctly.

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

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

With 100% schema coverage, the description adds crucial nuances: e.g., 'no field is formally required but usually at least contact_id and user_id', and details the repetition object structure. This goes beyond the schema's base definitions.

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

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

The description clearly states the tool manages sales orders (kb_order) and enumerates all specific actions (list, search, get, create, etc.), making the purpose unambiguous and distinguishing it from sibling tools like bexio_document_positions or bexio_invoices.

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

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

The description provides context for each action, e.g., 'positions cannot be updated here' and 'delete permanently'. However, it does not explicitly tell when to use alternative tools (e.g., bexio_document_positions for updating positions), leaving room for ambiguity.

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 include destructiveHint=true, and the description reinforces this by stating 'delete permanently deletes the payment — cannot be undone'. It also discloses non-obvious behavior: for update, the API takes the payment id in the request body, not the URL. This adds valuable 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?

The description is lengthy but well-organized: it starts with the overall purpose, lists actions with sub-requirements, and uses parenthetical notes. Each sentence adds necessary detail given the tool's complexity. Could be slightly more concise but earns a high score.

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?

Despite no output schema, the description covers all actions, input parameters, constraints, and edge cases. It explains validation rules and per-action requirements thoroughly, making it a complete reference for the tool's usage.

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%, but the description adds significant value by summarizing required fields per action, clarifying which fields are allowed or disallowed per payment type, and noting API quirks. This goes well 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 clearly states the tool manages outgoing payments for purchase bills and lists five specific actions (list, get, create, update, delete). It includes the API version and notes that payment ids are UUID strings. This differentiates it from sibling tools like bexio_banking_payments and bexio_bills.

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

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

The description provides explicit context for each action, including required parameters and constraints (e.g., bill must not be a draft for create, amount must not exceed pending_amount, validation on payment types). It does not explicitly exclude alternatives but the detail is sufficient for an agent to choose the correct action.

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 annotations (destructiveHint=true, readOnlyHint=false), the description discloses PATCH vs PUT behavior, deprecated endpoints, required fields for create, and that deletion is permanent, providing essential 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.

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

The description is thorough but well-structured by resource and action. It is slightly verbose but each sentence adds value; could benefit from tighter phrasing.

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

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

Given the tool's complexity (9 parameters, nested objects, multiple CRUD operations), the description covers all necessary aspects: resource-specific actions, required fields, API behaviors (PATCH/PUT), deprecated endpoints, and output expectations (PDF download). No missing critical information.

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?

Although schema coverage is 100%, the description adds critical meaning: which parameters apply to which resource/action, required vs optional fields, and special cases like ahv_number both on create and update, and full-object requirement for absence update.

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

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

The description opens with 'Manage bexio payroll (4.0 API): employees, their absences and paystub PDFs,' clearly defining the tool's scope and distinguishing it from sibling tools like bexio_accounting or bexio_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 description details when to use each resource and action, including API specifics (PATCH vs PUT) and deletion irreversibility, but does not explicitly contrast usage with sibling tools, though domain implicitly differentiates.

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 description adds valuable behavioral context beyond annotations: it mentions that delete is permanent, work package updates are partial PATCHes while milestone updates are POSTs, and list supports pagination with limit/offset. No contradictions with 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 informative and front-loaded with the core purpose, but it is somewhat lengthy and mixes multiple pieces of information in a single paragraph. A more structured format could improve readability, but it avoids wasted words.

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

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

Given the complexity (7 parameters, nested objects, multiple resources and actions), the description covers behavior well. It does not explain return values or list results format, but for a CRUD-like tool this is acceptable. The annotations and schema provide additional context.

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

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

The description groups fields by resource type and explains which fields apply to milestones vs. work packages. It clarifies that name is the only required field on create, and that payload is structured accordingly. This adds significant meaning beyond the schema's individual parameter descriptions.

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

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

The description clearly states it manages milestones and work packages of a project using the bexio 3.0 API, with specific verbs and resource names. It distinguishes from sibling tools by specifying the project-planning sub-resources.

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

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

The description explicitly explains how to set the resource, action, and project_id parameters, and outlines the required payload fields for each action. It does not explicitly state when not to use this tool, but the specificity is sufficient for most use cases.

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 (destructiveHint=true, readOnlyHint=false), the description discloses critical behavioral details: delete 'permanently deletes the project, cannot be undone', archive 'hides without deleting', and create requires specific fields. It also lists searchable fields and notes that search criteria are AND-combined. No contradictions with 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 well-structured by action, using a compact format with parentheses for details. It is relatively long but every sentence contributes useful information. It could be slightly more concise, but the organization is clear and front-loaded with the overall purpose.

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

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

Given the tool's complexity (10 actions, nested objects, 7 parameters), the description covers most aspects thoroughly: actions, required fields, searchable fields, ordering, and idempotency notes for delete/archive. However, it lacks information about the return value format (e.g., what fields are returned for list/get) and does not mention pagination details beyond limit/offset. This is a gap since no output schema is provided.

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?

While schema coverage is 100% (baseline 3), the description adds significant meaning: it explains that order_by supports '_desc' suffix, that searchable fields include name/contact_id/etc., that search criteria are AND-combined, and that payload required fields for create are name, pr_state_id, etc. It also clarifies special cases like document_nr usage. This adds value 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 clearly states that the tool manages projects via the bexio 2.0 API and lists all possible actions (list, search, get, create, update, delete, archive, unarchive, list_statuses, list_types). It also describes what a project consists of (name, status, type, etc.). This distinguishes it from sibling tools like bexio_tasks or bexio_timesheets by focusing exclusively on project 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?

The description provides explicit guidance for each action, including required parameters (e.g., id for get/update/delete/archive/unarchive, payload for create). It explains when to use 'archive' vs 'delete' (hides vs permanently deletes). However, it does not compare this tool to other bexio tools or state when not to use it, which would improve the score.

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?

Describes read-only status field, destructive deletion ('permanently deletes — cannot be undone'), and that update does not accept positions, adding context beyond annotations. Annotations include destructiveHint: true, consistent with the description. No contradiction.

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 informative but somewhat lengthy. However, it is front-loaded with core info (API, status, actions) and each sentence adds value. Minor redundancy (e.g., 'positions are create-only' mentioned twice). Still, overall structure is effective.

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

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

Given the complexity (6 params, nested payload, no output schema), the description covers actions, parameters, and constraints thoroughly. However, it does not describe the return value format (e.g., a purchase order object) which would be helpful since no output schema exists. Otherwise, it is comprehensive.

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%, but the description adds significant value: clarifies order_by fields and '_desc' suffix, notes payload fields typically required, explains status values (22 Draft, etc.), and specifies that positions are create-only. The description goes well beyond the schema descriptions.

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

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

The description clearly states it manages purchase orders, specifies the API version (bexio 3.0), numeric ids, and enumerates all five actions (list, get, create, update, delete) with distinct details, distinguishing it from siblings like bexio_invoices or bexio_orders.

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

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

Each action is explicitly described with its required parameters (e.g., get requires id, list uses limit/offset). Constraints like status being read-only, positions not accepted in update are noted. However, no explicit guidance on when to prefer this tool over siblings (e.g., bexio_orders for sales orders, bexio_invoices for invoices).

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 significant context beyond annotations: discloses that 'delete' is permanent, 'send' sends an email, 'pdf' can write to disk, and notes limitations like trial period email restriction. Also explains that 'viewed_by_client_at' is normally set by bexio. No contradiction with 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?

Well-organized with a status flow overview followed by action bullet points. While lengthy (17 actions), each sentence is informative and the structure is clear. No fluff, but could be slightly more streamlined.

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 complex tool with 17 actions and nested parameters, the description covers all necessary context: status flow, action-specific requirements, parameter constraints, and edge cases. No output schema exists, but return values are implied by actions.

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%, but description adds value: lists useful search fields, explains position variants and max count, clarifies document_nr logic, and describes edge cases like 'viewed_by_client_at' writability.

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?

Description clearly states 'Manage quotes/offers' and lists 17 distinct actions, each with a specific verb-resource combination. The resource is unambiguously quotes, distinguishing it from sibling tools like invoices or orders.

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

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

Detailed guidance for each action, including prerequisites (e.g., document_nr only when automatic numbering is off) and constraints (e.g., message must contain '[Network Link]'). However, it does not explicitly contrast with alternatives like bexio_invoices, though the tool name and sibling list make the distinction clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive; description adds that actions require 'stock_edit' scope and details each action's behavior, including searchable fields and ordering options.

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

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

Two sentences, front-loaded with purpose, no wasted words. Actions and parameters described compactly.

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

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

Covers actions, pagination, ordering, search, and scope. No output schema, but describes return as 'simple id/name records'. Lacks details on default limit but schema covers that.

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 descriptions; description adds specific searchable fields ('name, id') and valid order_by values, adding value 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?

Specifies verb 'Read' and resources 'stock locations and stock areas'. Distinguishes from sibling tools by domain and lists four concrete actions. Clear and specific.

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

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

No explicit guidance on when to use this tool vs alternatives among siblings. Prerequisite scope is stated, but no when-to-use or when-not-to-use comparisons.

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 indicate destructiveHint=true, and the description confirms that delete is permanent and cannot be undone. It also details that create requires specific fields. No additional behavioral traits beyond what annotations already provide are disclosed, but the description does not contradict 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 fairly concise given the complexity of eight actions and many parameters. It front-loads the general purpose and then details each action. Some redundancy exists (e.g., repeating 'order_by' for different actions), but overall it's well-structured and efficient.

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

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

For a multi-action tool with no output schema, the description is complete. It covers all eight actions, their required/optional parameters, and cross-references to other tools (list_statuses, list_priorities). The agent can correctly select and invoke the tool based on this description.

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

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

Schema coverage is 100%, so baseline is 3. The description adds some context, e.g., for search it lists searchable fields, and for create it notes required payload fields. However, it does not elaborate on parameters like info, place, or sub_contact_id beyond what the schema already describes.

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

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

The description clearly states it manages tasks/todos in bexio and enumerates eight specific actions (list, search, get, create, update, delete, list_priorities, list_statuses). It distinguishes itself from sibling tools like bexio_contacts or bexio_projects by focusing on task management.

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

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

The description provides detailed guidance per action: for search, it specifies search_criteria required; for create, it lists required fields (user_id, subject) and references list_statuses/list_priorities for status/priority IDs. It also explains order_by options. However, it doesn't explicitly state when to avoid certain actions or when to use alternatives.

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

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

Description adds behavioral context beyond annotations: delete is 'permanently delete ... cannot be undone', and read timesheets may contain 'stopwatch' tracking from UI. Annotations already signal destructiveHint=true, so the description reinforces and adds detail. No contradiction.

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 densely packed with information in a well-organized list format, front-loading the overall purpose. Every sentence is necessary and informative, with no wasted words.

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?

Despite lacking an output schema, the description covers all main actions and their constraints (required fields, pagination via limit/offset, order_by syntax, search criteria operators). It does not describe return values explicitly, but for a management tool with multiple actions, this is 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?

With 100% schema description coverage, baseline is 3. The description adds value by specifying searchable fields, required payload fields for create, and the tracking object's two variants (duration vs range) with examples. This supplements the schema's property descriptions.

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

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

The description clearly states it manages timesheets (time tracking entries) in bexio and enumerates all supported actions (list, search, get, create, update, delete, list_statuses). This specific verb-resource pairing distinguishes it clearly from sibling tools like bexio_projects or bexio_tasks.

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

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

The description provides explicit context for each action: e.g., 'list' returns all timesheets, 'search' requires search_criteria with specified searchable fields, 'create' requires certain payload fields. However, it does not compare this tool to siblings or state when not to use it, which is a minor gap.

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 (destructiveHint=true), the description warns that deletion cannot be undone and notes that certain fields (is_superadmin/is_accountant) are only returned for superadmins. It also explains that fictional users appear in dropdowns but cannot log in, adding valuable 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.

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

The description is well-structured with action names in quotes for easy scanning. It front-loads the main purpose and then enumerates actions. While slightly lengthy, it avoids redundancy and each sentence adds value.

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

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

Given the tool's complexity (multiple actions, 5 parameters, no output schema), the description is fairly complete. It covers all actions, their requirements, pagination limits, and behavioral notes. It could detail return values for specific actions (e.g., what 'me' returns), but overall it provides sufficient 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?

With 100% schema coverage, the baseline is 3. The description adds value by summarizing required payload fields for create_fictional (salutation_type, firstname, lastname, email) and clarifying that title_id is optional. It also explains the conditional inclusion of admin 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?

The description clearly specifies all actions (list, get, me, list_fictional, get_fictional, create_fictional, update_fictional, delete_fictional, permissions) and distinguishes between regular users (read-only) and fictional users (CRUD). This specificity differentiates it from sibling tools like bexio_contacts or bexio_master_data.

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

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

The description provides context on when to use each action (e.g., regular users are read-only, fictional users can be modified) and mentions optional parameters for pagination. However, it does not explicitly state when not to use this tool versus alternatives or provide direct comparisons to sibling tools.

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