Call any sevDesk API operation

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

With no annotations, the description fully bears the burden. It discloses key behaviors: parameter encoding (bracket syntax), mutation refusal under SEVDESK_READ_ONLY=true, and description-only mode under SEVDESK_DRY_RUN=true or dryRun parameter. The warning '⚠️ This tool can change data' further emphasizes mutability. All relevant behavioral traits are transparently documented.

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 of about 100 words, front-loading the core purpose. Each sentence contributes unique information (purpose, parameter mapping, encoding, mutation conditions). Slightly verbose in the middle, but overall efficient and well-structured. Loses a point for minor redundancy (e.g., 'are only described (not sent)' could be tighter).

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 (generic API caller, 4 parameters, no output schema), the description covers essential usage and behavior. However, it lacks any description of the return value or response structure, which is significant since there is no output schema. The term 'catalogue' is referenced but not explained (though understood via sibling tool sevdesk_list_operations). The description handles the basics but leaves the agent needing to infer response format.

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?

Schemas have 100% coverage, so baseline is 3. The description adds meaningful operational details beyond the schema: it clarifies that path parameters are taken by name from `params` and the remainder become query parameters, and it describes the bracket syntax for nested objects. The `dryRun` parameter behavior is also elaborated. These additions justify a score above baseline.

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

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

The description opens with 'Execute any operation from the catalogue', clearly stating the tool's purpose: a generic API caller. This distinguishes it from sibling tools, which are specific operations (e.g., sevdesk_list_contacts, sevdesk_create_invoice). The verb 'execute' and resource 'any operation' are precise.

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 how parameters are mapped (path from params by name, rest as query) and how nested objects are encoded, which is useful usage guidance. However, it does not explicitly state when to prefer this generic tool over sibling-specific tools, nor does it mention when not to use it (e.g., if a specific tool exists). The dry run and read-only behaviors are noted, but the high-level 'when to use' is left implicit.

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