Talon provides three well-named, read-only tools with clear verb-noun naming (talon_search, talon_read, talon_related). All tools have substantive descriptions (100-200 chars) explaining WHAT they do and WHEN to use them. Input schemas are present with typed parameters and descriptions. However, output schemas are not documented in the source code, the agent contract file shows only input definitions. Parameter descriptions are good but lack explicit constraints (e.g., limit ranges, depth bounds). No error handling guidance is visible. All three tools are read-only (low risk), but descriptions could better explain failure modes and recovery paths.

• Document output schemas for all three tools. Specify fields (e.g., talon_search returns [{path, score, snippet, scope}, ...]), types (string, number, array), and ordering (ranked by relevance). This enables agents to extract and chain results.
• Add parameter constraints: talon_search limit (1-100, default 20), depth (1-5, default 1), fromLine/maxLines (positive integers, maxLines ≤ 10000). Include these in descriptions: 'limit: Maximum results to return (1-100, default 20).'
• Add error recovery guidance to each tool description. E.g., talon_search: 'If no results found, try broader query or different mode (bm25 vs semantic). If scope not found, pass scopeAll=true to search all scopes.'
• Clarify talon_read 'raw' parameter: 'If true, return unprocessed note content; if false, apply markdown formatting and remove metadata. Default false.'
• Document pagination for talon_search if results can exceed limit. Specify whether it returns a next_cursor or offset for fetching additional results.