Object-type parameters lack internal schema definition. Tools like 'assign_to_categories', 'create_transaction', 'update_transaction', 'create_scheduled_transaction', 'update_scheduled_transaction' accept generic 'object' types with only a description string. LLMs cannot determine what fields these objects require, leading to hallucinated payloads and failed calls.
No output schemas documented anywhere. The code shows tools return data but does not specify the response structure. LLMs cannot plan downstream calls or extract specific fields when they don't know what structure to expect.
Document the internal schema for all 'object'-type parameters. For 'create_transaction', expand to: {"type":"object","properties":{"amount":{"type":"number"},"date":{"type":"string","format":"date"},"memo":{"type":"string"},"payee_id":{"type":"string"},"category_id":{"type":"string"}},"required":["amount","date","category_id"]}. This enables LLM validation and prevents hallucination.
Add output schemas to toolDefinitions.js. For each tool, document return types. E.g., list_budgets returns {"budgets":[{"id":"string","name":"string","currency_format":{...}}],"total_count":"number"}. This allows agents to plan chained calls.
Expand parameter descriptions to 80-150 characters with format and constraint hints. Replace 'Email parameter is required' with 'The user email address (format: [email protected]). Must match an authenticated YNAB account. Call list_ynab_accounts to see available emails.'
Add pagination parameters (limit: 1-100 default 20, offset: 0+) to all list_* tools and document result limits in descriptions. E.g., 'Returns up to 20 transactions. Use offset parameter to paginate through results.'
Declare enums for constrained parameters. For transaction operations, add enum: ["income", "expense", "transfer"]. For frequency in scheduled transactions, add enum: ["never", "daily", "weekly", "biWeekly", "twiceMonthly", "monthly", "everyOtherMonth", "quarterly", "yearly", "everyOtherYear"].
Add error guidance to write operation descriptions. E.g., 'If auth_code is invalid or expired, an AuthenticationError is returned. Call authenticate_ynab_account again with a fresh code.' and 'If the budget or account is locked, creation fails; try again after refresh.'
Parameter descriptions are too brief (mostly 50 chars or less). While all parameters have descriptions, they lack depth about expected format, constraints, and valid ranges. E.g., 'Email parameter is required' and 'Budget ID parameter is required' do not explain format, uniqueness, or derivation. LLMs cannot validate inputs without this detail.
No pagination parameters visible. List tools (list_budgets, list_accounts, list_categories, list_transactions, etc.) do not declare limit, offset, or cursor parameters. Without pagination, large result sets will exhaust context windows. Tools like list_transactions could return hundreds of records with no way to limit results.
No enums or constrained values declared. Parameters that should accept a fixed set (e.g., transaction type, category type, frequency) are described as free-form strings. LLMs will hallucinate invalid values, causing API errors.
No error guidance in tool descriptions. Descriptions do not indicate what errors can occur, how to recover, or when to retry. E.g., 'authenticate_ynab_account' does not explain what happens if the auth code is invalid or expired. Agents lack recovery strategies.
No idempotency declarations. Write operations like create_transaction, create_scheduled_transaction do not indicate whether they are idempotent. If retried, will they create duplicates? Agents need this info to safely retry on ambiguous failures.
Tool descriptions do not clarify prerequisites or dependencies. E.g., 'get_budget' requires both email and budgetId, but there's no hint that you must call list_budgets first if you don't have the budgetId. This forces agents to discover APIs through trial-and-error.
Add idempotency hints to tool descriptions for write operations. E.g., 'This operation is idempotent: calling it twice with the same transaction data will not create duplicates.' Or 'WARNING: Not idempotent, calling twice may create duplicate scheduled transactions.'
Include dependency hints in get_* and update_* descriptions. E.g., 'Requires a valid budgetId (obtain from list_budgets) and accountId (obtain from list_accounts). Call those discovery tools first if you don't have the IDs.'
Add a 'minimum' and 'maximum' constraint hint to numeric or date parameters. E.g., for list_transactions filter: 'Date range limit: maximum 365 days. Avoid querying more than 1 year of history at once.'
Document response field cardinality. E.g., for list_transactions: 'Returns array of up to 20 transaction objects. Each includes: id, date, amount, category_id, payee_id, memo. See get_transaction for full transaction schema details.'
Add sample error message templates to tool docs. E.g., 'Invalid categoryId: "cat_999", category does not exist in this budget. Call list_categories to see available categories.' This pattern matches the rubric's guidance on actionable errors.