Firefly III MCP Server

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

Annotations indicate idempotent, non-destructive writes. The description adds critical behavioral context beyond annotations: it clarifies partial-update semantics (PATCH-like behavior) where omitted fields are preserved rather than nulled, which is essential for correct invocation.

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?

Extremely efficient two-sentence structure. The first establishes purpose, the second provides the essential partial-update warning. No redundancy or extraneous 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?

Adequate for a standard CRUD update with good annotations, but lacks mention of error conditions (e.g., invalid ID), return value structure, or constraints on field combinations (e.g., account_role only valid for asset accounts, noted in schema but not 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?

With 100% schema coverage, the baseline is 3. The description elevates this by explaining the collective semantics of optional parameters via 'Only provide fields you want to change,' clarifying that null/omitted values leave existing data untouched rather than clearing it.

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

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

The description states the specific action ('Update') and resource ('an existing account'), with 'existing' implicitly distinguishing it from firefly_create_account. However, it does not explicitly differentiate from firefly_get_account or firefly_delete_account.

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 instruction 'Only provide fields you want to change' provides clear usage guidance for the partial-update semantics, but there is no explicit guidance on when to choose this tool over create_account (for new accounts) or whether this preserves transaction history versus delete_account.

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