list_transactions

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

It discloses the default 30-day range when no dates are provided and notes that output is hydrated (names instead of IDs). This is useful beyond the schema. Since there are no annotations, the description carries the burden; however, it does not explicitly mention that the operation is read-only or address error handling, leaving some transparency gaps.

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: three sentences covering purpose, filters, and output. It is front-loaded with the primary action and includes no fluff or redundant 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 10 parameters and no output schema, the description covers the main behaviors (modes, defaults, filters, pagination, output). However, the account_id inaccuracy and lack of explanation about how the two account filters relate make it incomplete. It also does not clarify behavior when an id is used with filters.

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 aggregates filters and adds the default-date context, but it mentions 'account_id' which does not exist in the schema; the schema has separate plaid_account_id and manual_account_id. This is misleading and could cause incorrect invocation. Although the schema has thorough descriptions, this inaccuracy reduces the value added.

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 'List or look up Lunch Money transactions' with explicit modes (with/without id). This distinguishes it from sibling tools like manage_transaction or bulk_update_transactions, which imply write operations. The resource is specific and the verb is clear.

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

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

It provides clear context for when to use the tool: without an id for filtered lists, with an id for a single lookup. It also explains default date behavior and pagination. However, it doesn't explicitly state alternatives or when-not-to-use cases, but the context is sufficient.

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