Add calc, mail, playing and finance example tools

All read-only: each command is fixed in its tool file, so the model
fills parameters but can never reach mailctl tag or firefly tx add.
qalc reads "17.5% of 240" as a modulo, so the calc hint shows percent
as a factor.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 51 insertions, 0 deletions

diff --git a/examples/tools/finance.sh b/examples/tools/finance.sh
new file mode 100755
index 0000000..3c6f768
--- /dev/null
+++ b/examples/tools/finance.sh
@@ -0,0 +1,51 @@
+#!/bin/bash
+# desktop-assistant tool: personal finance from Firefly III (read-only).
+# Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License version 2 as published
+# by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
+# Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+# finance.sh WHAT [DAYS]: WHAT is balances (active asset accounts),
+# budgets (this month, spent against the limit) or spending (withdrawals in
+# the last DAYS days, default 30: total and the 10 largest). Only firefly's
+# list commands run here: nothing is recorded or edited.
+
+set -uo pipefail
+
+ff() { firefly "$@" || { echo "firefly $1 $2 failed" >&2; exit 1; }; }
+
+case "${1:-}" in
+balances)
+    ff account list --type asset | jq -r '.[] | select(.active)
+        | "\(.name): \(.current_balance | tonumber * 100 | round / 100) \(.currency_code)"'
+    ;;
+budgets)
+    ff budget list | jq -r '.[] | select(.active)
+        | "\(.name): spent \([.spent[].sum | tonumber] | add // 0 | fabs * 100 | round / 100)"
+          + (if .auto_budget_amount then " of \(.auto_budget_amount | tonumber)" else "" end)
+          + " \(.currency_code // "")"'
+    ;;
+spending)
+    days="${2:-30}"
+    since=$(date -d "$days days ago" +%F) || exit 1
+    ff tx list --since "$since" --all --flat 2>/dev/null | jq -r --arg since "$since" '
+        [.[] | select(.type == "withdrawal") | .amount |= tonumber]
+        | "spent since \($since): \(map(.amount) | add // 0 | . * 100 | round / 100) in \(length) payments",
+          (sort_by(-.amount)[:10][]
+           | "\(.date[:10]) \(.amount * 100 | round / 100) \(.destination_name): \(.description)")'
+    ;;
+*)
+    echo "what must be balances, budgets or spending" >&2
+    exit 1
+    ;;
+esac