get_uncategorized_transactions

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

With no annotations provided, the description carries full burden of behavioral disclosure. It discloses the sorting behavior (alphabetical by description) and default limit of 100, which is useful. However, it doesn't cover what the output looks like, whether pagination is supported beyond the limit parameter, or any safety/read-only implications. The read-only nature is implied by the name and purpose but not explicitly stated. It's better than many but leaves some 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 well-structured with a clear opening sentence stating the primary behavior, followed by a paragraph explaining the use case, and then a bulleted argument list. Every sentence earns its place — the use-case paragraph adds real value rather than padding. No redundancy or fluff.

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 an output schema (which covers return values) and only 3 simple optional parameters. The description fully covers the purpose, use case, sorting behavior, and all parameters. It's complete for a straightforward read/list tool. It's slightly short of a 5 because it doesn't explicitly note read-only behavior or describe pagination/limits beyond the default, but given the output schema fills return-value details, this 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 description coverage is 0%, and there are no enum or format constraints in the schema. The description compensates by explaining each parameter: type filters by transaction type ('income' or 'expense'), search is a keyword filter for description, and limit is max records with a default of 100. However, the description adds some value beyond the bare schema, achieving the baseline 3, but doesn't go further with details like exact matching semantics, wildcard support, or case sensitivity of the search parameter.

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 retrieves uncategorized transactions sorted alphabetically by description, with the specific purpose of systematic categorization after bulk import. This distinguishes it from siblings like get_transactions (general retrieval) and list_categories (category listing). The verb+resource+sorting behavior is specific and well-defined.

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 states when to use this tool: 'Designed for systematic categorization after bulk import' and specifically 'retrieve transactions imported without categories.' It also explains WHY it's useful (sorting groups similar merchants, enabling fast bulk updates via update_transaction), which requires reading the update_transaction sibling tool. This is strong usage guidance that implicitly contrasts with get_transactions.

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