Manage transaction category

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

With no annotations, the description must carry the full burden of behavioral disclosure. It reveals that 'Delete uses Preview/Apply', but does not mention that other operations might also use preview/apply, nor does it explain side effects, permissions, or reversibility. The lack of detail about the preview/apply mechanism for non-delete operations is a significant gap.

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 sentence that front-loads the key actions and adds a specific constraint about delete. It is concise and has no wasted words, though the extreme brevity contributes to the lack of parameter guidance. It earns its place but is slightly under-specified for the tool's 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?

The tool has 7 parameters, nested objects, 6 operations, no output schema, and no annotations, yet the description is only 16 words. It does not explain how operations map to parameters, what preview/apply means for each operation, what the response format is, or what the confirmation_token is for. This is wholly inadequate for the tool's complexity.

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 0% and the description does not compensate at all. It lists operations (create, update, hide, etc.) but never links them to the parameters (category, patch, orders, category_ref, mode, confirmation_token). For instance, it says 'reorder' but doesn't mention the 'orders' array. The description adds no semantic value beyond the schema's raw parameter names.

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 explicitly lists the verbs 'Create, update, hide, unhide, reorder or delete' with the resource 'transaction categories', clearly distinguishing it from read-only siblings like list_categories. It also adds a specific note that 'Delete uses Preview/Apply', which further clarifies the tool's scope.

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

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

The description implies usage by enumerating all category management operations. However, it does not explicitly state when to use this tool over alternatives (e.g., list_categories for viewing), nor does it explain when to use preview vs. apply mode beyond the delete case. This is clear context but lacks exclusions or alternative references.

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