{"service":"bonusly-mcp","version":"0.1.0","protocol_version":"2025-11-25","methods":[{"name":"adminActivateUser","title":"Activate user","description":"Reactivate a deactivated user in the caller's company. Schedules background activation.","inputSchema":{"type":"object","properties":{"user_id":{"type":"string"}},"additionalProperties":false,"required":["user_id"]},"annotations":{"readOnlyHint":false}},{"name":"adminCreateAward","title":"Create Award","description":"Create a new custom award in the caller's company. Defines conditions, budget, period, approval levels, and giver-bot metadata.","inputSchema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"description":{"type":["null","string"]},"conditions_operator":{"type":"string","minLength":1},"conditions":{"type":"array","items":{"type":"object","properties":{"attr":{"type":"string","minLength":1},"value":{"type":"string","minLength":1}},"required":["attr","value"]}},"budget_per_period":{"type":["null","integer"]},"period_type":{"type":"string","minLength":1},"amount":{"type":["null","integer"]},"amount_editable":{"anyOf":[{},{}],"not":{"type":"null"}},"title":{"type":"string","minLength":1},"message":{"type":["null","string"]},"message_editable":{"anyOf":[{},{}],"not":{"type":"null"}},"visibility":{"type":"string","minLength":1},"visibility_editable":{"anyOf":[{},{}],"not":{"type":"null"}},"hide_giver":{"anyOf":[{},{}],"not":{"type":"null"}},"approval_process_levels":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer","not":{"type":"null"}},"allowed_approver_ids":{"type":"array","items":{}}},"required":[]}}},"additionalProperties":false,"required":["name","conditions_operator","conditions","period_type","visibility"]},"outputSchema":{"type":"object","properties":{"award":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"amount":{"type":"integer"},"amount_editable":{"type":"boolean"},"state":{"type":"string"},"conditions":{"type":"array","items":{}},"budget_per_period":{"type":"integer"},"period_type":{"type":"string"}},"required":["id","name","description","amount","amount_editable","state","conditions","budget_per_period","period_type"]}},"required":["award"]},"annotations":{"readOnlyHint":false}},{"name":"adminCreateGiveBalanceIncrement","title":"Create give balance increment","description":"Add a giving balance increment (e.g. admin_initiated_boost) to a user in the caller's company.","inputSchema":{"type":"object","properties":{"user_id":{"type":"string"},"amount":{"type":"integer","not":{"type":"null"}},"type":{"type":"string","minLength":1,"enum":["admin_initiated_boost","redemption_boost","program_boost","drawdown","program_drawdown","refund","program_refund"]},"description":{"type":"string","minLength":1}},"additionalProperties":false,"required":["user_id","amount","type","description"]},"outputSchema":{"type":"object","properties":{"line_item":{"type":"object","properties":{"amount":{"type":"integer"},"type":{"type":"string"},"description":{"type":"string"},"created_at":{"type":"string"}},"required":["amount","type","description","created_at"]}},"required":["line_item"]},"annotations":{"readOnlyHint":false}},{"name":"adminCreateUser","title":"Create user","description":"Invite a new user to the caller's company by work email. Optional fields include first_name, last_name, manager_email, hired_on (YYYY-MM-DD), company_admin, and custom_properties (for example department). If the email belongs to a recently deactivated user in the same company, this reactivates them instead of creating a duplicate. For explicit reactivation of a known deactivated profile, prefer adminActivateUser. Admin-only — same policy as the Bizy UserAdmin agent.","inputSchema":{"type":"object","properties":{"email":{"type":"string","minLength":1},"first_name":{"type":["null","string"]},"last_name":{"type":["null","string"]},"manager_email":{"type":["null","string"]},"hired_on":{"type":["null","string"],"format":"date"},"date_of_birth":{"type":["null","string"],"format":"date"},"country":{"type":["null","string"]},"cost_center":{"type":["null","string"]},"preferred_first_name":{"type":["null","string"]},"slug":{"type":["null","string"]},"company_admin":{"type":["null","boolean"]},"user_mode":{"type":["null","string"]},"time_zone":{"type":["null","string"]},"external_unique_id":{"type":["null","string"]},"permission_ids":{"type":["null","array"]},"budget_boost":{"type":["null","integer"]},"custom_properties":{"type":["null","object"]}},"additionalProperties":false,"required":["email"]},"outputSchema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"display_name":{"type":"string"},"username":{"type":"string"},"locale":{"type":"string"},"time_zone":{"type":"string"},"status":{"type":"string"},"user_mode":{"type":"string"},"custom_properties":{"type":"object","properties":{},"required":[]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","email","first_name","last_name","display_name","username","locale","time_zone","status","user_mode","custom_properties","created_at","updated_at"]}},"required":["user"]},"annotations":{"readOnlyHint":false}},{"name":"adminDeactivateUser","title":"Deactivate user","description":"Schedule deactivation (archive) for a user in the caller's company. Requires user_id. Cannot deactivate the last remaining admin or integration-protected users when manual management is disabled. Admin-only — same policy as the Bizy UserAdmin agent.","inputSchema":{"type":"object","properties":{"user_id":{"type":"string"}},"additionalProperties":false,"required":["user_id"]},"outputSchema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"status":{"type":"string"}},"required":["id","email","status"]},"message":{"type":"string"}},"required":["user","message"]},"annotations":{"readOnlyHint":false}},{"name":"adminDeleteAward","title":"Delete Award","description":"Soft-delete an award in the caller's company and deactivate its giver bot.","inputSchema":{"type":"object","properties":{"award_id":{"type":"string"}},"additionalProperties":false,"required":["award_id"]},"outputSchema":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string"},"message":{"type":"string"}},"required":["success","id","message"]},"annotations":{"destructiveHint":true,"readOnlyHint":false}},{"name":"adminGetGiveBalance","title":"Get give balance","description":"Fetch a user's giving balance line items with pagination.","inputSchema":{"type":"object","properties":{"user_id":{"type":"string"},"page":{"type":["null","integer"],"exclusiveMinimum":0},"per_page":{"type":["null","integer"],"exclusiveMinimum":0}},"additionalProperties":false,"required":["user_id"]},"outputSchema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"}},"required":["id","email"]},"line_items":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"integer"},"type":{"type":"string"},"description":{"type":"string"},"created_at":{"type":"string"}},"required":["amount","type","description","created_at"]}},"total_count":{"type":"integer"},"page":{"type":"integer"},"per_page":{"type":"integer"}},"required":["user","line_items","total_count","page","per_page"]},"annotations":{"readOnlyHint":true}},{"name":"adminGetMcpUsageDetails","title":"Admin get MCP usage details","description":"Get MCP usage details by company, user, date range, class,\nmethod, or name. Returns per-method totals plus a per-date\nbreakdown of each `(user_id, occurred_at)` event and the\ndistinct `name` values observed in the range. Paginated by\nmethod via `page_size` + cursor. Admin-only. Does not track\nits own usage.\n","inputSchema":{"type":"object","properties":{"user_id":{"type":"null","anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"start_date":{"type":["null","string"],"format":"date"},"end_date":{"type":["null","string"],"format":"date"},"klass":{"type":["null","string"]},"method_name":{"type":["null","string"]},"name":{"type":["null","string"]},"page_size":{"type":"integer","not":{"type":"null"},"exclusiveMinimum":0,"maximum":200},"cursor":{"type":["null","string"]}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"start_date":{"type":"string"},"end_date":{"type":"string"},"total_groups":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"company_id":{"type":"string"},"method_name":{"type":"string"},"total_usage":{"type":"integer"},"names":{"type":"array","items":{}},"usages":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"occurrences":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string"},"occurred_at":{"type":"string"}},"required":["user_id","occurred_at"]}}},"required":["date","occurrences"]}}},"required":["company_id","method_name","total_usage","names","usages"]}},"next_cursor":{}},"required":["start_date","end_date","total_groups","results"]},"annotations":{"readOnlyHint":true}},{"name":"adminGetMcpUsageTotals","title":"Admin get MCP usage totals","description":"Get MCP usage totals by company, user, date range, class, method, or name. Does not track usage.","inputSchema":{"type":"object","properties":{"user_id":{"type":"null","anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"start_date":{"type":["null","string"],"format":"date"},"end_date":{"type":["null","string"],"format":"date"},"klass":{"type":["null","string"]},"method_name":{"type":["null","string"]},"name":{"type":["null","string"]}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"start_date":{"type":"string"},"end_date":{"type":"string"},"count":{"type":"integer"}},"required":["start_date","end_date","count"]},"annotations":{"readOnlyHint":true}},{"name":"adminGetUser","title":"Admin get user","description":"Get a single ACTIVE user's full admin profile by ID, email,\nor name. Deactivated users surface as not found in this\nphase. Returns id, names, email, department, manager,\ncustom_properties, locale, time_zone, hired_on, and\nlast_active_at, plus three role-related fields the caller\nmust not conflate: role (coarse \"admin\" / \"employee\"),\ncompany_admin (legacy single-flag), and permission_names\n(humanized fine-grained admin capabilities). When the\nidentifier is ambiguous, returns a disambiguation payload\nlisting candidates so the caller can re-issue the request\nwith a chosen ID. Admin-only — gated on the same policy\nas the Bizy chat UserAdmin agent.\n","inputSchema":{"type":"object","properties":{"identifier":{"type":"string","minLength":1}},"additionalProperties":false,"required":["identifier"]},"outputSchema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"preferred_first_name":{"type":"string"},"email":{"type":"string"},"status":{"type":"string"},"user_mode":{"type":"string"},"time_zone":{"type":"string"},"display_name":{"type":"string"},"locale":{"type":"string"},"role":{"type":"string"},"company_admin":{"type":"boolean"},"permission_names":{"type":"array","items":{"type":"string"}},"department":{"type":"string"},"manager":{"type":"object","properties":{"id":{"type":"string"},"display_name":{"type":"string"},"email":{"type":"string"}},"required":["id","display_name","email"]},"hired_on":{"type":"string"},"last_active_at":{"type":"string"},"created_at":{"type":"string"},"custom_properties":{"type":"object","properties":{"department":{"type":"string"}},"required":["department"]}},"required":["id","first_name","last_name","preferred_first_name","email","status","user_mode","time_zone","display_name","locale","role","company_admin","permission_names","department","manager","hired_on","last_active_at","created_at","custom_properties"]}},"required":["user"]},"annotations":{"readOnlyHint":true}},{"name":"adminListAwards","title":"List Awards","description":"List custom awards in the caller's company. Supports filtering by state ('active' or 'inactive') and cursor pagination. Pass page_size and (optionally) state on the first call; on subsequent calls pass only the returned next_cursor — the state filter is encoded in the cursor and carried forward automatically.","inputSchema":{"type":"object","properties":{"state":{"type":"string","minLength":1,"enum":["active","inactive"]},"page_size":{"type":"integer","not":{"type":"null"},"exclusiveMinimum":0,"maximum":100},"cursor":{"type":["null","string"]}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"records":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"amount":{"type":"integer"},"amount_editable":{"type":"boolean"},"state":{"type":"string"}},"required":["id","name","description","amount","amount_editable","state"]}},"next_cursor":{"type":"string"}},"required":["records","next_cursor"]},"annotations":{"readOnlyHint":true}},{"name":"adminListUsers","title":"Admin list users","description":"List active users in the authenticated caller's company with\noptional filters: name/email search, department (exact\nmatch), role (admin / employee), manager presence (managers /\nwithout_manager), and Bizy enrollment (bizy_enabled /\nbizy_disabled). Returns paginated structured rows plus\ncounts, available departments, and the filters that were\napplied. Pagination is cursor-based: pass `page_size` on the\nfirst call and the returned `next_cursor` on subsequent\ncalls. Admin-only — gated on the same policy as the Bizy\nchat UserAdmin agent.\n","inputSchema":{"type":"object","properties":{"search":{"type":["null","string"]},"department":{"type":["null","string"]},"role":{"type":["null","string"],"enum":["all","admin","employee"]},"filter":{"type":["null","string"],"enum":["all","managers","without_manager","bizy_enabled","bizy_disabled"]},"page_size":{"type":"integer","not":{"type":"null"},"exclusiveMinimum":0,"maximum":25},"cursor":{"type":["null","string"]}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"user_mode":{"type":"string"},"display_name":{"type":"string"},"role":{"type":"string"},"department":{"type":"string"},"manager":{"type":"object","properties":{"id":{"type":"string"},"display_name":{"type":"string"},"email":{"type":"string"}},"required":["id","display_name","email"]}},"required":["id","email","user_mode","display_name","role","department","manager"]}},"total_count":{"type":"integer"},"counts":{"type":"object","properties":{"active":{"type":"integer"},"deactivated":{"type":"integer"}},"required":["active","deactivated"]},"available_departments":{"type":"array","items":{"type":"string"}},"applied_filters":{"type":"object","properties":{"department":{"type":"string"}},"required":["department"]},"next_cursor":{"type":"string"}},"required":["users","total_count","counts","available_departments","applied_filters","next_cursor"]},"annotations":{"readOnlyHint":true}},{"name":"adminParticipationReport","title":"Admin Participation Report","description":"Returns participation report data for the caller's company, including giving/receiving rates by group (department, location, etc.) or manager and team metrics.\nSupports two views: 'giving_and_receiving' (participation by group) and 'managers_and_teams' (per-manager metrics including direct reports recognized and unrecognized counts).\nRequires a date range (start_date and end_date as YYYY-MM-DD) and an optional grouping dimension (e.g. 'department', 'location').\nRequires global admin or reports admin access.\n","inputSchema":{"type":"object","properties":{"report_view":{"type":"string","minLength":1},"start_date":{"type":"string","minLength":1},"end_date":{"type":"string","minLength":1},"custom_property_group":{"type":["null","string"]},"include_trend":{"type":["null","boolean"]}},"additionalProperties":false,"required":["report_view","start_date","end_date"]},"outputSchema":{"type":"object","properties":{"company_participation":{"type":"object","properties":{"group_name":{"type":"string"},"giving_participation_rate":{"type":"number"},"receiving_participation_rate":{"type":"number"},"active_user_count":{"type":"integer"},"total_user_count":{"type":"integer"}},"required":["group_name","giving_participation_rate","receiving_participation_rate","active_user_count","total_user_count"]},"bonusly_average":{"type":"object","properties":{"giving_participation_rate":{"type":"number"},"receiving_participation_rate":{"type":"number"}},"required":["giving_participation_rate","receiving_participation_rate"]},"peer_average":{"type":"object","properties":{"giving_participation_rate":{"type":"number"},"receiving_participation_rate":{"type":"number"}},"required":["giving_participation_rate","receiving_participation_rate"]},"records":{"type":"array","items":{"type":"object","properties":{"group_name":{"type":"string"},"giving_participation_rate":{"type":"number"},"receiving_participation_rate":{"type":"number"},"active_user_count":{"type":"integer"},"total_user_count":{"type":"integer"}},"required":["group_name","giving_participation_rate","receiving_participation_rate","active_user_count","total_user_count"]}}},"required":["company_participation","bonusly_average","peer_average","records"]},"annotations":{"readOnlyHint":true}},{"name":"adminRewardsApproveRedemption","title":"Admin Rewards Approve Redemption","description":"Approves a pending reward redemption for the caller's company.","inputSchema":{"type":"object","properties":{"reward_id":{"type":"string"}},"additionalProperties":false,"required":["reward_id"]},"outputSchema":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string"},"aasm_state":{"type":"string"}},"required":["success","id","aasm_state"]},"annotations":{"readOnlyHint":false}},{"name":"adminRewardsDeclineRedemption","title":"Admin Rewards Decline Redemption","description":"Declines a reward redemption for the caller's company.","inputSchema":{"type":"object","properties":{"reward_id":{"type":"string"}},"additionalProperties":false,"required":["reward_id"]},"outputSchema":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string"},"aasm_state":{"type":"string"}},"required":["success","id","aasm_state"]},"annotations":{"readOnlyHint":false}},{"name":"adminRewardsFulfillRedemption","title":"Admin Rewards Fulfill Redemption","description":"Fulfills a custom reward redemption for the caller's company.","inputSchema":{"type":"object","properties":{"reward_id":{"type":"string"}},"additionalProperties":false,"required":["reward_id"]},"outputSchema":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string"},"aasm_state":{"type":"string"}},"required":["success","id","aasm_state"]},"annotations":{"readOnlyHint":false}},{"name":"adminRewardsRedemptionsReport","title":"Admin Rewards Redemptions Report","description":"Returns paginated reward redemption records for the caller's company. Supports filtering by state, user email, date range, and fulfillment status.","inputSchema":{"type":"object","properties":{"aasm_state":{"type":["null","string"]},"page":{"type":["null","integer"]},"per_page":{"type":["null","integer"]},"user_email":{"type":["null","string"]},"start_date":{"type":["null","string"]},"end_date":{"type":["null","string"]},"unfulfilled":{"type":["null","boolean"]},"range":{"type":["null","string"]},"sort":{"type":["null","string"]},"direction":{"type":["null","string"]}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"custom_user_properties":{"type":"array","items":{"type":"string"}},"show_credit_card_offset":{"type":"boolean"},"disable_approve_all":{"type":"boolean"},"pagination":{"type":"object","properties":{"current_page":{"type":"integer"},"total_pages":{"type":"integer"},"total_count":{"type":"integer"},"per_page":{"type":"integer"}},"required":["current_page","total_pages","total_count","per_page"]},"rewards":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"user":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string"}},"required":["first_name","last_name","email"]},"reward_name":{"type":"string"},"swag_color":{},"swag_size":{},"reward_type":{"type":"string"},"total_value_local_currency":{"type":"object","properties":{"cents":{"type":"integer"},"currency":{"type":"string"},"formatted":{"type":"string"}},"required":["cents","currency","formatted"]},"points_redeemed":{"type":"object","properties":{"cents":{"type":"integer"},"currency":{"type":"string"},"formatted":{"type":"string"}},"required":["cents","currency","formatted"]},"credit_card_offset_local_currency":{"type":"object","properties":{"cents":{"type":"integer"},"currency":{"type":"string"},"formatted":{"type":"string"}},"required":["cents","currency","formatted"]},"points_cost":{"type":"integer"},"amount_billed_usd":{"type":"object","properties":{"cents":{"type":"integer"},"currency":{"type":"string"},"formatted":{"type":"string"}},"required":["cents","currency","formatted"]},"approved_by":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string"}},"required":["first_name","last_name","email"]},"provider":{"type":"string"},"fulfilled":{"type":"boolean"},"refunded_at":{},"refunded_by":{},"declined_by":{}},"required":["id","created_at","user","reward_name","reward_type","total_value_local_currency","points_redeemed","credit_card_offset_local_currency","points_cost","amount_billed_usd","approved_by","provider","fulfilled"]}}},"required":["custom_user_properties","show_credit_card_offset","disable_approve_all","pagination","rewards"]},"annotations":{"readOnlyHint":true}},{"name":"adminRewardsRefundRedemption","title":"Admin Rewards Refund Redemption","description":"Refunds a custom reward redemption for the caller's company. Superadmins must use the super_admin path instead.","inputSchema":{"type":"object","properties":{"reward_id":{"type":"string"}},"additionalProperties":false,"required":["reward_id"]},"outputSchema":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string"},"aasm_state":{"type":"string"}},"required":["success","id","aasm_state"]},"annotations":{"destructiveHint":true,"readOnlyHint":false}},{"name":"adminRewardsTotalsReport","title":"Admin Rewards Totals Report","description":"Returns per-user or grouped reward spend totals for the caller's company. Use group_by to aggregate by a custom property or country.","inputSchema":{"type":"object","properties":{"range":{"type":["null","string"]},"start_date":{"type":["null","string"]},"end_date":{"type":["null","string"]},"include_archived":{"type":["null","boolean"]},"direction":{"type":["null","string"]},"sort":{"type":["null","string"]},"group_by":{"type":["null","string"]},"page":{"type":["null","integer"]},"per_page":{"type":["null","integer"]},"hidden_columns":{"type":["null","string"]}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"grouped":{"type":"boolean"},"show_credit_card_offset":{"type":"boolean"},"show_local_currency":{"type":"boolean"},"show_usd_totals":{"type":"boolean"},"show_reward_country":{"type":"boolean"},"show_user_modes":{"type":"boolean"},"custom_user_properties":{"type":"array","items":{"type":"string"}},"group_by_options":{"type":"array","items":{"type":"string"}},"pagination":{"type":"object","properties":{"current_page":{"type":"integer"},"total_pages":{"type":"integer"},"total_count":{"type":"integer"},"per_page":{"type":"integer"}},"required":["current_page","total_pages","total_count","per_page"]},"total_user_count":{"type":"integer"},"users":{"type":"array","items":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string"},"country":{"type":"string"},"user_mode":{"type":"string"},"avatar_url":{"type":"string"},"custom_properties":{"type":"object","properties":{"department":{"type":"string"}},"required":["department"]},"role_suffix":{"type":"string"}},"required":["id","first_name","last_name","email","country","user_mode","avatar_url","custom_properties","role_suffix"]},"gift_card_total":{"type":"object","properties":{"cents":{"type":"integer"},"currency":{"type":"string"},"formatted":{"type":"string"}},"required":["cents","currency","formatted"]},"total_debited_total":{"type":"object","properties":{"cents":{"type":"integer"},"currency":{"type":"string"},"formatted":{"type":"string"}},"required":["cents","currency","formatted"]}},"required":["user","gift_card_total","total_debited_total"]}},"totals":{"type":"object","properties":{"gift_card":{"type":"object","properties":{"cents":{"type":"integer"},"currency":{"type":"string"},"formatted":{"type":"string"}},"required":["cents","currency","formatted"]},"total_debited":{"type":"object","properties":{"cents":{"type":"integer"},"currency":{"type":"string"},"formatted":{"type":"string"}},"required":["cents","currency","formatted"]}},"required":["gift_card","total_debited"]},"entire_company_totals":{"type":"object","properties":{"gift_card":{"type":"object","properties":{"cents":{"type":"integer"},"currency":{"type":"string"},"formatted":{"type":"string"}},"required":["cents","currency","formatted"]},"total_debited":{"type":"object","properties":{"cents":{"type":"integer"},"currency":{"type":"string"},"formatted":{"type":"string"}},"required":["cents","currency","formatted"]}},"required":["gift_card","total_debited"]}},"required":["grouped","show_credit_card_offset","show_local_currency","show_usd_totals","show_reward_country","show_user_modes","custom_user_properties","group_by_options","pagination","total_user_count","users","totals","entire_company_totals"]},"annotations":{"readOnlyHint":true}},{"name":"adminRewardsUnfulfillRedemption","title":"Admin Rewards Unfulfill Redemption","description":"Marks a fulfilled custom reward redemption as unfulfilled for the caller's company.","inputSchema":{"type":"object","properties":{"reward_id":{"type":"string"}},"additionalProperties":false,"required":["reward_id"]},"outputSchema":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string"},"aasm_state":{"type":"string"}},"required":["success","id","aasm_state"]},"annotations":{"readOnlyHint":false}},{"name":"adminShowAward","title":"Show Award","description":"Fetch a single award in the caller's company by id.","inputSchema":{"type":"object","properties":{"id":{"type":"string"}},"additionalProperties":false,"required":["id"]},"outputSchema":{"type":"object","properties":{"award":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"amount":{"type":"integer"},"amount_editable":{"type":"boolean"},"state":{"type":"string"},"conditions":{"type":"array","items":{}},"budget_per_period":{"type":"integer"},"period_type":{"type":"string"}},"required":["id","name","description","amount","amount_editable","state","conditions","budget_per_period","period_type"]}},"required":["award"]},"annotations":{"readOnlyHint":true}},{"name":"adminUpdateAward","title":"Update Award","description":"Update an existing award in the caller's company. Any subset of mutable fields may be passed.","inputSchema":{"type":"object","properties":{"award_id":{"type":"string"},"name":{"type":"string","minLength":1},"description":{"type":["null","string"]},"conditions_operator":{"type":"string","minLength":1},"conditions":{"type":"array","items":{"type":"object","properties":{"attr":{"type":"string","minLength":1},"value":{"type":"string","minLength":1}},"required":["attr","value"]}},"budget_per_period":{"type":["null","integer"]},"period_type":{"type":"string","minLength":1},"amount":{"type":["null","integer"]},"amount_editable":{"anyOf":[{},{}],"not":{"type":"null"}},"title":{"type":"string","minLength":1},"message":{"type":["null","string"]},"message_editable":{"anyOf":[{},{}],"not":{"type":"null"}},"state":{"type":"string","minLength":1},"visibility":{"type":"string","minLength":1},"visibility_editable":{"anyOf":[{},{}],"not":{"type":"null"}},"hide_giver":{"anyOf":[{},{}],"not":{"type":"null"}},"approval_process_levels":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer","not":{"type":"null"}},"allowed_approver_ids":{"type":"array","items":{}}},"required":[]}}},"additionalProperties":false,"required":["award_id"]},"outputSchema":{"type":"object","properties":{"award":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"amount":{"type":"integer"},"amount_editable":{"type":"boolean"},"state":{"type":"string"},"conditions":{"type":"array","items":{}},"budget_per_period":{"type":"integer"},"period_type":{"type":"string"}},"required":["id","name","description","amount","amount_editable","state","conditions","budget_per_period","period_type"]}},"required":["award"]},"annotations":{"readOnlyHint":false}},{"name":"adminUpdateUser","title":"Update user","description":"Update admin-managed attributes for a user in the caller's company (names, email, manager_email, clear_manager (remove manager), company_admin, locale, time_zone, custom_properties such as department, permission_ids, etc.). Requires user_id. Manual edits may be blocked for HRIS-managed users. Admin-only — same policy as the Bizy UserAdmin agent.","inputSchema":{"type":"object","properties":{"user_id":{"type":"string"},"locale":{"type":["null","string"]},"first_name":{"type":["null","string"]},"last_name":{"type":["null","string"]},"email":{"type":["null","string"]},"preferred_first_name":{"type":["null","string"]},"slug":{"type":["null","string"]},"manager_email":{"type":["null","string"]},"hired_on":{"type":["null","string"],"format":"date"},"date_of_birth":{"type":["null","string"],"format":"date"},"country":{"type":["null","string"]},"cost_center":{"type":["null","string"]},"company_admin":{"type":["null","boolean"]},"user_mode":{"type":["null","string"]},"time_zone":{"type":["null","string"]},"external_unique_id":{"type":["null","string"]},"budget_boost":{"type":["null","integer"]},"permission_ids":{"type":["null","array"]},"password":{"type":["null","string"]},"remove_avatar":{"type":["null","boolean"]},"custom_properties":{"type":["null","object"]},"intercom_id":{"type":["null","string"]},"otp_required_for_login":{"type":["null","boolean"]},"clear_manager":{"type":["null","boolean"]}},"additionalProperties":false,"required":["user_id"]},"outputSchema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"display_name":{"type":"string"},"username":{"type":"string"},"locale":{"type":"string"},"time_zone":{"type":"string"},"status":{"type":"string"},"user_mode":{"type":"string"},"custom_properties":{"type":"object","properties":{},"required":[]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","email","first_name","last_name","display_name","username","locale","time_zone","status","user_mode","custom_properties","created_at","updated_at"]}},"required":["user"]},"annotations":{"readOnlyHint":false}},{"name":"adminUsersLastRecognized","title":"Admin Users Last Recognized","description":"Returns a paginated list of users along with when they were last recognized by a specified manager.\nPass a full array of user IDs (up to 20 per page) and optionally a manager_id.\nPagination is cursor-based and slices the provided user_ids array — pass page_size on the first\ncall and the returned next_cursor on subsequent calls (along with the same user_ids array).\nThe manager_id is encoded in the cursor and carried forward automatically; it does not need to\nbe re-supplied on subsequent pages.\nWhen manager_id is provided, last_recognized_by_manager_at reflects the most recent recognition\ngiven by that manager while they were actually the user's manager at that time.\nReturns null for users with no recognition from the specified manager.\nRequires global admin, finance admin, reports admin, or manager access.\n","inputSchema":{"type":"object","properties":{"user_ids":{"type":"array","items":{"type":"string"}},"manager_id":{"type":"string"},"page_size":{"type":"integer","not":{"type":"null"},"minimum":1,"maximum":20},"cursor":{"type":["null","string"]}},"additionalProperties":false,"required":["user_ids"]},"outputSchema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string"},"profile_pic_url":{"type":"string"},"display_name":{"type":"string"},"last_recognized_by_manager_at":{"type":"string"}},"required":["id","username","profile_pic_url","display_name","last_recognized_by_manager_at"]}},"total_count":{"type":"integer"},"next_cursor":{"type":"string"}},"required":["users","total_count","next_cursor"]},"annotations":{"readOnlyHint":true}},{"name":"deleteRecognition","title":"Delete recognition","description":"Delete (undo) a recognition you gave, scoped to your company. Mirrors the\n`DELETE /api/v1/bonuses/:id` endpoint.\n\nInput:\n- `id` (string, required) — the recognition's BSON ObjectId.\n\nUndoing is only permitted for recognition you gave/initiated within\n24 hours of creation and whose points\nhaven't already been spent — or by a company admin. This is destructive\nand cannot be undone.\n","inputSchema":{"type":"object","properties":{"id":{"type":"string","description":"The recognition's BSON ObjectId."}},"required":["id"],"additionalProperties":false,"strict":true},"outputSchema":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string"},"message":{"type":"string"}},"required":["success","id","message"]},"annotations":{"destructiveHint":true,"readOnlyHint":false}},{"name":"getCompany","title":"Get company","description":"Returns metadata for the authenticated caller's company — name, locale, plan, feature flags, subscription state, and other profile fields.","inputSchema":{"type":"object","properties":{},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"country":{"type":"string"},"locale":{"type":"string"},"time_zone":{"type":"string"},"points_ratio":{"type":"integer"},"currency_name":{"type":"string"},"currency_symbol":{"type":"string"}},"required":["id","name","country","locale","time_zone","points_ratio","currency_name","currency_symbol"]}},"required":["company"]},"annotations":{"readOnlyHint":true}},{"name":"getDirectReports","title":"Get direct reports","description":"Get the users in the authenticated caller's company who report directly to a given manager. Cross-company manager IDs return no results. Supports a name/email search and cursor pagination.","inputSchema":{"type":"object","properties":{"user_id":{"type":"string"},"search":{"type":["null","string"]},"page_size":{"type":"integer","not":{"type":"null"},"exclusiveMinimum":0,"maximum":100},"cursor":{"type":["null","string"]}},"additionalProperties":false,"required":["user_id"]},"outputSchema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"display_name":{"type":"string"},"username":{"type":"string"},"locale":{"type":"string"},"time_zone":{"type":"string"},"status":{"type":"string"},"user_mode":{"type":"string"}},"required":["id","email","first_name","last_name","display_name","username","locale","time_zone","status","user_mode"]}},"next_cursor":{}},"required":["users"]},"annotations":{"readOnlyHint":true}},{"name":"getGroupRecognitionRecipientCount","title":"Get group recognition recipient count","description":"Resolve a Bonusly user group by name, slug, or type and return how many\nrecipients an actual group post would reach within your company — plus a\npaginated roster of those recipients (id and name).\n\nAccepted inputs for `group_name`:\n- \"everyone\" → the @everyone group (all active receiving users in the\n  company)\n- A department name (e.g. \"Engineering\")\n- A location name (e.g. \"Berlin\")\n- A team — the manager's name plus \"team\" (e.g. \"Sarah's team\") or the\n  team slug\n\nReturns `recipient_count` plus the resolved `group_name` / `group_type` /\n`group_slug`, and a `members` array of {id, name}. Membership is\npaginated: `members` is one page (size `limit`, default\n50, max\n200); when more pages\nexist `next_cursor` is non-null — pass it back as `cursor` to fetch the\nnext page. Keep the rest of the input (notably `group_name`) identical\nacross pages.\n\nReturns an error if no matching group is found, or if more than one\nnon-reserved group matches the same name (e.g. a department and a\nlocation both named \"Sales\").\n","inputSchema":{"type":"object","properties":{"group_name":{"type":"string","minLength":1},"limit":{"type":["null","integer"]},"cursor":{"type":["null","string"]}},"additionalProperties":false,"required":["group_name"]},"outputSchema":{"type":"object","properties":{"recipient_count":{"type":"integer"},"group_name":{"type":"string"},"group_type":{"type":"string"},"group_slug":{"type":"string"},"description":{"type":"string"},"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"next_cursor":{"type":"string"}},"required":["recipient_count","group_name","group_type","group_slug","description","members","next_cursor"]},"annotations":{"readOnlyHint":true}},{"name":"getManagerChain","title":"Get manager chain","description":"Walk the manager chain upward from a given user in the authenticated caller's company, returning the user's manager, that manager's manager, and so on up to a top-level user. The chain is ordered closest-first.","inputSchema":{"type":"object","properties":{"user_id":{"type":"string"}},"additionalProperties":false,"required":["user_id"]},"outputSchema":{"type":"object","properties":{"chain":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"display_name":{"type":"string"},"username":{"type":"string"},"locale":{"type":"string"},"time_zone":{"type":"string"},"status":{"type":"string"},"user_mode":{"type":"string"}},"required":["id","email","first_name","last_name","display_name","username","locale","time_zone","status","user_mode"]}}},"required":["chain"]},"annotations":{"readOnlyHint":true}},{"name":"getMyRedemptions","title":"Get my redemptions","description":"List YOUR own reward redemptions (newest first), scoped to your company.\nMirrors the `/api/v1/users/:user_id/redemptions` endpoint for the calling\nuser. Returns each redemption's state, catalog/reward details, and claim\nand certificate URLs.\n\nPagination is cursor-based:\n- `limit` (integer, optional) — page size, 1–100 (default 20).\n- `cursor` (string, optional) — pass back the `next_cursor` from a prior\n  response to fetch the next page. Keep `limit` identical across pages\n  (the cursor carries the page size).\n\n`total_count` is the full count of your redemptions; `redemptions` is one\npage. When more pages exist, `next_cursor` is non-null.\n","inputSchema":{"type":"object","properties":{"limit":{"type":"integer","description":"Page size (1–100, default 20)."},"cursor":{"type":"string","description":"Opaque cursor from a prior response's `next_cursor`."}},"required":[],"additionalProperties":false,"strict":true},"outputSchema":{"type":"object","properties":{"redemptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"catalog_item_id":{"type":"string"},"created_at":{"type":"string"},"state":{"type":"string"},"certificate_url":{"type":"string"},"claim_url":{},"auto_approvable":{"type":"boolean"},"reward_details":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"amount_in_points":{"type":"integer"}},"required":["id","name","amount_in_points"]}},"required":["id","catalog_item_id","created_at","state","certificate_url","auto_approvable","reward_details"]}},"total_count":{"type":"integer"},"next_cursor":{"type":"string"}},"required":["redemptions","total_count","next_cursor"]},"annotations":{"readOnlyHint":true}},{"name":"getPointsBalance","title":"Get points balance","description":"Get the authenticated user's current points balances and lifetime stats.\nReturns giving balance, earned/redeemable balance (earnings), monthly budget,\ncurrency, exchange rate, lifetime earnings, lifetime given, and lifetime redeemed.\nAlso returns `exchange_rate` (points per 1 unit of `currency`) and\n`purchasing_power_parity_enabled` so callers can answer fiat-conversion\nquestions like \"how much is N points worth?\".\nUse this for any question about your own points balance, earnings, or recognition stats.\n","inputSchema":{"type":"object","properties":{},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"points_name":{"type":"string"},"currency":{"type":"string"},"exchange_rate":{"type":"integer"},"purchasing_power_parity_enabled":{"type":"boolean"},"giving_balance":{"type":"integer"},"giving_balance_description":{"type":"string"},"earned_balance":{"type":"integer"},"earned_balance_description":{"type":"string"},"monthly_budget":{"type":"integer"},"lifetime_earnings":{"type":"integer"},"lifetime_given":{"type":"integer"},"lifetime_redeemed":{"type":"integer"},"infinite_budget":{"type":"boolean"}},"required":["id","name","email","points_name","currency","exchange_rate","purchasing_power_parity_enabled","giving_balance","giving_balance_description","earned_balance","earned_balance_description","monthly_budget","lifetime_earnings","lifetime_given","lifetime_redeemed","infinite_budget"]},"annotations":{"readOnlyHint":true}},{"name":"getRecognition","title":"Get recognition","description":"Fetch a single recognition (bonus) by its id, scoped to your company.\nReturns the recognition's giver, hashtags, amount, the cleaned message,\nand family position — the same shape the other recognition tools emit\nper row.\n\nInput:\n- `id` (string, required) — the recognition's BSON ObjectId.\n\nA recognition that doesn't exist in your company is reported as not found.\n","inputSchema":{"type":"object","properties":{"id":{"type":"string","description":"The recognition's BSON ObjectId."}},"required":["id"],"additionalProperties":false,"strict":true},"outputSchema":{"type":"object","properties":{"recognition":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"reason":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}},"primary_hashtag":{"type":"string"},"giver":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"active":{"type":"boolean"}},"required":["id","name","email","active"]},"amount":{"type":"integer"},"recipient_count":{"type":"integer"},"top_level":{"type":"boolean"},"parent_bonus_id":{}},"required":["id","created_at","reason","hashtags","primary_hashtag","giver","amount","recipient_count","top_level"]}},"required":["recognition"]},"annotations":{"readOnlyHint":true}},{"name":"getRecognitionFeed","title":"Get recognition feed","description":"Return a page of the recognition feed for the authenticated caller's company —\nthe same content shown in Bonusly's web home feed (top-level posts in\nreverse-chronological order).\n\nFilters (all optional, all combined as AND):\n- `departments`, `locations`, `teams` — arrays of group names; combine with\n  `listDepartments` / `listLocations` to discover valid values.\n- `hashtags` — array of hashtag strings; leading `#` is optional and\n  matching is case-insensitive (e.g. both `\"teamwork\"` and `\"#teamwork\"`\n  match `#teamwork`).\n- `recognition_types` — subset of celebrations, awards, incentives, peer.\n  Call `listRecognitionTypes` to enumerate the values.\n- `current_user_only` — subset of given, received\n  (recognition the caller gave / received).\n- `giver_id`, `receiver_id` — restrict to a specific user.\n- `relevance` — when `true`, bias toward the caller's most-relevant\n  colleagues (mirrors the web \"Relevant\" tab).\n\nPagination is cursor-based. `recognitions` is a single page (size `limit`,\ndefault 25, max\n100); when more pages exist\n`next_cursor` is non-null — pass it back as `cursor` to fetch the next\npage. Keep the rest of the input identical across pages.\n\nEach row carries giver + receivers, amount, reason, hashtags, and top-level\nvs add-on/comment shape. Add-on rows themselves are not inlined to keep\npages small.\n","inputSchema":{"type":"object","properties":{"departments":{"type":["null","array"]},"locations":{"type":["null","array"]},"teams":{"type":["null","array"]},"hashtags":{"type":["null","array"]},"recognition_types":{"type":["null","array"]},"current_user_only":{"type":["null","array"]},"giver_id":{"type":["null","string"]},"receiver_id":{"type":["null","string"]},"relevance":{"type":["null","boolean"]},"limit":{"type":["null","integer"]},"cursor":{"type":["null","string"]}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"recognitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"reason":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}},"primary_hashtag":{"type":"string"},"giver":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"active":{"type":"boolean"}},"required":["id","name","email","active"]},"receivers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"active":{"type":"boolean"}},"required":["id","name","email","active"]}},"amount":{"type":"integer"},"top_level":{"type":"boolean"},"parent_bonus_id":{}},"required":["id","created_at","reason","hashtags","primary_hashtag","giver","receivers","amount","top_level"]}},"next_cursor":{"type":"string"},"note":{"type":"string"}},"required":["recognitions","next_cursor","note"]},"annotations":{"readOnlyHint":true}},{"name":"getRecognitionGiven","title":"Get recognition given","description":"List recognition (bonuses) given BY a user to others within your company. Returns\nrecipients, hashtags, the recognition message, and the giver's per-recognition spend.\nUse for \"When did a user recognize X?\", \"What have they recognized people for?\", or\n\"How many points did a user give this month?\".\n\nIdentify the giver with `target_user` (an ID, email address, or name); omit it to look up\nthe authenticated caller. Optionally narrow to recognition given TO a specific person with\n`receiver_user`, or to a group with `target_group`.\n\nCost model (important for math): a recognition's `points_per_recipient` is the amount on the\npost; the giver pays `points_per_recipient * recipient_count`. Use\n`total_points_spent_by_giver` for the giver-side total — never split a post amount across\nrecipients, and never sum the per-row `cost` across `recognitions` (that array is one page;\nthe summary totals cover the full window).\n\nTime window: pass `start_date` and `end_date` (ISO `YYYY-MM-DD`) for calendar ranges\n(\"this month\", a specific month). `days_back` is a rolling lookback (default 90, max 1825)\nand is only correct for \"last N days\".\n\nCursor pagination: set the filters and `page_size` on the first call; to fetch the next page\npass ONLY the returned `next_cursor` (it encodes the filters, page size, and position — no\nother arguments are needed or read). A null `next_cursor` means there are no more pages.\n","inputSchema":{"type":"object","properties":{"target_user":{"type":["null","string"]},"receiver_user":{"type":["null","string"]},"target_group":{"type":["null","string"]},"start_date":{"type":["null","string"]},"end_date":{"type":["null","string"]},"days_back":{"type":["null","integer"]},"page_size":{"type":"integer","not":{"type":"null"},"exclusiveMinimum":0,"maximum":50},"cursor":{"type":["null","string"]}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"}},"required":["id","name","email"]},"time_period":{"type":"object","properties":{"start_date":{"type":"string"},"end_date":{"type":"string"},"time_zone":{"type":"string"}},"required":["start_date","end_date","time_zone"]},"recognition_count":{"type":"integer"},"total_recognition_count":{"type":"integer"},"total_points_spent_by_giver":{"type":"integer"},"recognitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"reason":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}},"primary_hashtag":{"type":"string"},"receivers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"active":{"type":"boolean"}},"required":["id","name","email","active"]}},"recipient_count":{"type":"integer"},"points_per_recipient":{"type":"integer"},"cost":{"type":"integer"},"amount":{"type":"integer"}},"required":["id","created_at","reason","hashtags","primary_hashtag","receivers","recipient_count","points_per_recipient","cost","amount"]}},"cost_model_note":{"type":"string"},"next_cursor":{"type":"string"}},"required":["user","time_period","recognition_count","total_recognition_count","total_points_spent_by_giver","recognitions","cost_model_note","next_cursor"]},"annotations":{"readOnlyHint":true}},{"name":"getRecognitionGivenToUsers","title":"Get recognition given to users","description":"Returns when the authenticated caller last gave peer recognition to each of the\nspecified users. Pass up to 20 user IDs; the response includes one\nentry per requested user with a `last_recognized_at` timestamp (null when the\ncaller has never recognized that user).\n\nUse for \"Have I recognized these people recently?\", \"When did I last give\nrecognition to each of my teammates?\", or \"Which of these users have I never\nrecognized?\".\n\nAll user IDs must belong to the caller's company. The caller's own ID is\naccepted but `last_recognized_at` will always be null (you cannot recognize\nyourself). Duplicate IDs are deduplicated before querying.\n","inputSchema":{"type":"object","properties":{"user_ids":{"type":"array","items":{"type":"string"},"maxItems":20}},"additionalProperties":false,"required":["user_ids"]},"outputSchema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string"},"display_name":{"type":"string"},"profile_pic_url":{"type":"string"},"last_recognized_at":{"type":"string"}},"required":["id","username","display_name","profile_pic_url","last_recognized_at"]}},"total_count":{"type":"integer"}},"required":["users","total_count"]},"annotations":{"readOnlyHint":true}},{"name":"getRecognitionReceived","title":"Get recognition received","description":"List recognition (bonuses) received BY a user within your company. Returns who gave them\nrecognition, the hashtags used, and the recognition message — plus windowed earned totals.\nUse this to understand what someone has been recognized for, or for \"how many points did a\nuser earn/receive this month?\".\n\nIdentify the user with `target_user` (an ID, email address, or name); omit it to look up the\nauthenticated caller.\n\nTime window: pass `start_date` and `end_date` (ISO `YYYY-MM-DD`) for calendar-based ranges\n(\"this month\", \"last month\", a specific month). `days_back` is a rolling lookback (default 90,\nmax 1825) and is only correct when the request is explicitly \"last N days\".\n\nFor windowed earned totals use `total_points_received` (the full-window sum of points earned)\nand `total_recognition_count` (full-window count). Never sum the per-row `amount` across\n`recognitions` — that array is one page and will undercount.\n\nPagination is cursor-based. `recognitions` is a single page (size `limit`, default\n20, max 50);\nwhen more pages exist `next_cursor` is non-null — pass it back as `cursor` to fetch the next\npage. Keep the rest of the input identical across pages.\n","inputSchema":{"type":"object","properties":{"target_user":{"type":["null","string"]},"target_group":{"type":["null","string"]},"start_date":{"type":["null","string"]},"end_date":{"type":["null","string"]},"days_back":{"type":["null","integer"]},"limit":{"type":["null","integer"]},"cursor":{"type":["null","string"]},"individual_only":{"type":["null","boolean"]}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"}},"required":["id","name","email"]},"time_period":{"type":"object","properties":{"start_date":{"type":"string"},"end_date":{"type":"string"},"time_zone":{"type":"string"}},"required":["start_date","end_date","time_zone"]},"recognition_count":{"type":"integer"},"total_recognition_count":{"type":"integer"},"total_points_received":{"type":"integer"},"recognitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"reason":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}},"primary_hashtag":{"type":"string"},"giver":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"active":{"type":"boolean"}},"required":["id","name","email","active"]},"amount":{"type":"integer"},"recipient_count":{"type":"integer"},"top_level":{"type":"boolean"},"parent_bonus_id":{}},"required":["id","created_at","reason","hashtags","primary_hashtag","giver","amount","recipient_count","top_level"]}},"next_cursor":{"type":"string"},"note":{"type":"string"}},"required":["user","time_period","recognition_count","total_recognition_count","total_points_received","recognitions","next_cursor","note"]},"annotations":{"readOnlyHint":true}},{"name":"getRedemption","title":"Get redemption","description":"Fetch a single reward redemption by its id, scoped to your company.\nReturns the redemption's state, catalog/reward details, and claim and\ncertificate URLs — the same shape as the `/api/v1/redemptions/:id`\nendpoint.\n\nInput:\n- `id` (string, required) — the redemption's (reward's) BSON ObjectId.\n\nYou can read your OWN redemptions; reading someone else's requires a\nrewards-admin role. A redemption that doesn't exist in your company —\nor that you're not allowed to see — is reported as not found.\n","inputSchema":{"type":"object","properties":{"id":{"type":"string","description":"The redemption's (reward's) BSON ObjectId."}},"required":["id"],"additionalProperties":false,"strict":true},"outputSchema":{"type":"object","properties":{"id":{"type":"string"},"catalog_item_id":{"type":"string"},"created_at":{"type":"string"},"state":{"type":"string"},"certificate_url":{"type":"string"},"claim_url":{},"auto_approvable":{"type":"boolean"},"reward_details":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"amount_in_points":{"type":"integer"}},"required":["id","name","amount_in_points"]}},"required":["id","catalog_item_id","created_at","state","certificate_url","auto_approvable","reward_details"]},"annotations":{"readOnlyHint":true}},{"name":"getReportingTree","title":"Get reporting tree","description":"Walk the reporting tree below a given user in the authenticated caller's company. Returns layers: layer 0 is direct reports, layer 1 is direct reports' reports, etc. `depth` controls how many layers to include (default 1, max 5).","inputSchema":{"type":"object","properties":{"user_id":{"type":"string"},"depth":{"type":"integer","not":{"type":"null"},"minimum":1,"maximum":5}},"additionalProperties":false,"required":["user_id"]},"outputSchema":{"type":"object","properties":{"root":{"type":"object","properties":{"id":{"type":"string"},"display_name":{"type":"string"}},"required":["id","display_name"]},"layers":{"type":"array","items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"display_name":{"type":"string"}},"required":["id","display_name"]}}}},"required":["root","layers"]},"annotations":{"readOnlyHint":true}},{"name":"getUser","title":"Get user","description":"Resolve a single user within the caller's company by id, email or name.\nReturns the user's profile fields.\n\nPass the user's BSON ObjectId, email, or full display name as\n`identifier`. When the name matches multiple people, a disambiguation\npayload is returned listing candidates — re-call with one of the\ncandidate ids to get a definitive result.\n","inputSchema":{"type":"object","properties":{"identifier":{"type":"string","minLength":1}},"additionalProperties":false,"required":["identifier"]},"outputSchema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"display_name":{"type":"string"},"username":{"type":"string"},"locale":{"type":"string"},"time_zone":{"type":"string"},"status":{"type":"string"},"user_mode":{"type":"string"},"custom_properties":{"type":"object","properties":{},"required":[]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","email","first_name","last_name","display_name","username","locale","time_zone","status","user_mode","custom_properties","created_at","updated_at"]}},"required":["user"]},"annotations":{"readOnlyHint":true}},{"name":"getUsers","title":"Get users","description":"Bulk-fetch users by a list of user IDs within the authenticated caller's company.","inputSchema":{"type":"object","properties":{"user_ids":{"type":"array","items":{"type":"string"}}},"additionalProperties":false,"required":["user_ids"]},"outputSchema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"display_name":{"type":"string"},"username":{"type":"string"},"locale":{"type":"string"},"time_zone":{"type":"string"},"status":{"type":"string"},"user_mode":{"type":"string"}},"required":["id","email","first_name","last_name","display_name","username","locale","time_zone","status","user_mode"]}}},"required":["users"]},"annotations":{"readOnlyHint":true}},{"name":"giveRecognition","title":"Give recognition","description":"Send recognition (a bonus) to one or more colleagues on behalf of the\nauthenticated caller. Inputs: one or more recipients, an integer points\namount, a free-form reason, and one company hashtag.\n\nInputs:\n- `recipients` (array of strings) — each entry is a user id, email address,\n  or display name.\n- `amount` (integer) — points to give. Pass 0 only if your company allows zero-point.\n- `reason` (string) — free-form recognition message (no need to include @mentions or\n  `+amount` — they're synthesized from `recipients` and `amount`).\n- `hashtag` (string) — one company hashtag without the leading `#` (e.g. \"teamwork\").\n\nWhen any required input is missing or a recipient cannot be resolved, the response\neither carries a `requestedSchema` (for clients that declared `elicitation` at\ninitialize) or a standard `INVALID_PARAMS` error.\n\nReturns the new bonus id and a permalink path on success.\n","inputSchema":{"type":"object","properties":{"recipients":{"type":"array","description":"One or more recipients as user ids, email addresses, or display names.","items":{"type":"string"}},"amount":{"type":"integer","description":"Points to give (integer). 0 is permitted only if the company allows zero-point."},"reason":{"type":"string","description":"Free-form recognition message."},"hashtag":{"type":"string","description":"One company hashtag, without the leading `#`."}},"required":[],"additionalProperties":false,"strict":true},"outputSchema":{"type":"object","properties":{"success":{"type":"boolean"},"bonus_id":{"type":"string"},"link":{"type":"string"},"message":{"type":"string"},"recipients":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"amount":{"type":"integer"},"hashtag":{"type":"string"},"reason":{"type":"string"}},"required":["success","bonus_id","link","message","recipients","amount","hashtag","reason"]},"annotations":{"readOnlyHint":false}},{"name":"listAwards","title":"List Awards","description":"List custom awards in the caller's company. Supports cursor pagination. Pass type ('claimable' or 'manual') and page_size on the first call; on subsequent calls pass only the returned next_cursor.","inputSchema":{"type":"object","properties":{"type":{"type":["null","string"],"enum":["claimable","manual"]},"page_size":{"type":"integer","not":{"type":"null"},"exclusiveMinimum":0,"maximum":100},"cursor":{"type":["null","string"]}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"awards":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"amount":{"type":"integer"},"amount_editable":{"type":"boolean"},"state":{"type":"string"}},"required":["id","name","description","amount","amount_editable","state"]}},"next_cursor":{}},"required":["awards"]},"annotations":{"readOnlyHint":true}},{"name":"listDepartments","title":"List departments","description":"List the distinct departments configured for users in the authenticated caller's company, with a user count for each. Supports prefix-match search on the department name and cursor pagination.","inputSchema":{"type":"object","properties":{"search":{"type":["null","string"]},"page_size":{"type":"integer","not":{"type":"null"},"exclusiveMinimum":0,"maximum":100},"cursor":{"type":["null","string"]}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"departments":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"user_count":{"type":"integer"}},"required":["name","user_count"]}},"next_cursor":{"type":"string"}},"required":["departments","next_cursor"]},"annotations":{"readOnlyHint":true}},{"name":"listLocations","title":"List locations","description":"List the distinct locations configured for users in the authenticated caller's company, with a user count for each. Supports prefix-match search on the location name and cursor pagination.","inputSchema":{"type":"object","properties":{"search":{"type":["null","string"]},"page_size":{"type":"integer","not":{"type":"null"},"exclusiveMinimum":0,"maximum":100},"cursor":{"type":["null","string"]}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"locations":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"user_count":{"type":"integer"}},"required":["name","user_count"]}},"next_cursor":{"type":"string"}},"required":["locations","next_cursor"]},"annotations":{"readOnlyHint":true}},{"name":"listRecognitionTypes","title":"List recognition types","description":"Return the recognition-type values accepted by the `recognition_types` filter\non `getRecognitionFeed`. Each entry has a machine-readable `value` (pass this\ninto the filter) and a human-readable `name`.\n","inputSchema":{"type":"object","properties":{},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"recognition_types":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"name":{"type":"string"}},"required":["value","name"]}}},"required":["recognition_types"]},"annotations":{"readOnlyHint":true}},{"name":"listTopLevelUsers","title":"List top-level users","description":"List the users in the authenticated caller's company who have no manager. These are the entry points into the org chart — pair with `getReportingTree` or `getDirectReports` to walk down. Supports a name/email search and cursor pagination.","inputSchema":{"type":"object","properties":{"search":{"type":["null","string"]},"page_size":{"type":"integer","not":{"type":"null"},"exclusiveMinimum":0,"maximum":100},"cursor":{"type":["null","string"]}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"display_name":{"type":"string"},"username":{"type":"string"},"locale":{"type":"string"},"time_zone":{"type":"string"},"status":{"type":"string"},"user_mode":{"type":"string"}},"required":["id","email","first_name","last_name","display_name","username","locale","time_zone","status","user_mode"]}},"next_cursor":{}},"required":["users"]},"annotations":{"readOnlyHint":true}},{"name":"listUsersInDepartment","title":"List users in a department","description":"List the users in the authenticated caller's company who belong to a specific department (exact match). Supports a name/email search and cursor pagination.","inputSchema":{"type":"object","properties":{"department":{"type":"string","minLength":1},"search":{"type":["null","string"]},"page_size":{"type":"integer","not":{"type":"null"},"exclusiveMinimum":0,"maximum":100},"cursor":{"type":["null","string"]}},"additionalProperties":false,"required":["department"]},"outputSchema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"display_name":{"type":"string"},"username":{"type":"string"},"locale":{"type":"string"},"time_zone":{"type":"string"},"status":{"type":"string"},"user_mode":{"type":"string"}},"required":["id","email","first_name","last_name","display_name","username","locale","time_zone","status","user_mode"]}},"next_cursor":{}},"required":["users"]},"annotations":{"readOnlyHint":true}},{"name":"listUsersInLocation","title":"List users in a location","description":"List the users in the authenticated caller's company who belong to a specific location (exact match). Supports a name/email search and cursor pagination.","inputSchema":{"type":"object","properties":{"location":{"type":"string","minLength":1},"search":{"type":["null","string"]},"page_size":{"type":"integer","not":{"type":"null"},"exclusiveMinimum":0,"maximum":100},"cursor":{"type":["null","string"]}},"additionalProperties":false,"required":["location"]},"outputSchema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"display_name":{"type":"string"},"username":{"type":"string"},"locale":{"type":"string"},"time_zone":{"type":"string"},"status":{"type":"string"},"user_mode":{"type":"string"}},"required":["id","email","first_name","last_name","display_name","username","locale","time_zone","status","user_mode"]}},"next_cursor":{}},"required":["users"]},"annotations":{"readOnlyHint":true}},{"name":"me","title":"Me","description":"Returns the authenticated user's profile (identity, locale, account state). Does not include company information, balances, or permissions.","inputSchema":{"type":"object","properties":{},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"preferred_first_name":{"type":"string"},"display_name":{"type":"string"},"username":{"type":"string"},"locale":{"type":"string"},"time_zone":{"type":"string"},"country":{"type":"string"},"status":{"type":"string"},"user_mode":{"type":"string"},"profile_pic_url":{"type":"string"},"created_at":{"type":"string"}},"required":["id","email","first_name","last_name","preferred_first_name","display_name","username","locale","time_zone","country","status","user_mode","profile_pic_url","created_at"]},"annotations":{"readOnlyHint":true}},{"name":"searchRecognitions","title":"Search recognitions","description":"Search recognition (bonuses) in your company using natural language. Combines semantic\n(vector) and keyword (BM25) retrieval, so themes like \"leadership during difficult times\"\nand exact terms like a project codename or hashtag both work. Returns ranked excerpts\nwith the giver, the source bonus id, and a link.\n\nPass `query` (required) on the first call, with an optional `limit`\n(default 10, max 25). For subsequent pages echo the returned\n`next_cursor` back as `cursor` — the cursor preserves the original `query` and `limit`,\nso you do not need to (and should not) re-send them. `next_cursor` is null when there\nare no more pages.\n","inputSchema":{"type":"object","properties":{"query":{"type":"string","description":"Natural language search query describing the theme, concept, or keyword to find. Required on the first call; for paginated follow-ups, pass `cursor` instead."},"limit":{"type":"integer","description":"Maximum number of results to return per page (default: 10, max: 25). Ignored when `cursor` is supplied (the cursor carries the original page size)."},"cursor":{"type":"string","description":"Opaque cursor from a previous response's `next_cursor`. When supplied, the original `query` and `limit` are restored from the cursor — do not re-send them."}},"required":[],"additionalProperties":false,"strict":true},"outputSchema":{"type":"object","properties":{"query":{"type":"string"},"result_count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"url":{"type":"string"},"excerpt":{"type":"string"},"score":{"type":"number"},"metadata":{"type":"object","properties":{"hashtags":{"type":"array","items":{"type":"string"}}},"required":["hashtags"]},"giver_name":{"type":"string"},"created_at":{"type":"string"}},"required":["type","id","url","excerpt","score","metadata","giver_name","created_at"]}},"next_cursor":{"type":"string"}},"required":["query","result_count","results","next_cursor"]},"annotations":{"readOnlyHint":true}},{"name":"searchUsers","title":"Search users","description":"Search users in the authenticated caller's company by name or email, with optional\nfilters on location, department, manager, and reports. Supports cursor pagination —\npass the returned `next_cursor` as `cursor` to fetch the next page.\n","inputSchema":{"type":"object","properties":{"search_term":{"type":"string","minLength":1},"and_conditions":{"type":"array","items":{"not":{"type":"null"}}},"or_conditions":{"type":"array","items":{"not":{"type":"null"}}},"exclude_conditions":{"type":["null","array"]},"page_size":{"type":"integer","not":{"type":"null"},"exclusiveMinimum":0,"maximum":100},"cursor":{"type":["null","string"]}},"additionalProperties":false,"required":["search_term"]},"outputSchema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"display_name":{"type":"string"},"username":{"type":"string"},"locale":{"type":"string"},"time_zone":{"type":"string"},"status":{"type":"string"},"user_mode":{"type":"string"}},"required":["id","email","first_name","last_name","display_name","username","locale","time_zone","status","user_mode"]}},"next_cursor":{}},"required":["users"]},"annotations":{"readOnlyHint":true}},{"name":"showAward","title":"Show Award","description":"Fetch a single award in the caller's company by id.","inputSchema":{"type":"object","properties":{"id":{"type":"string"}},"additionalProperties":false,"required":["id"]},"outputSchema":{"type":"object","properties":{"award":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"amount":{"type":"integer"},"amount_editable":{"type":"boolean"},"state":{"type":"string"},"conditions":{"type":"array","items":{}},"budget_per_period":{"type":"integer"},"period_type":{"type":"string"}},"required":["id","name","description","amount","amount_editable","state","conditions","budget_per_period","period_type"]}},"required":["award"]},"annotations":{"readOnlyHint":true}},{"name":"updateRecognition","title":"Update recognition","description":"Edit the message (reason) of an existing recognition you gave, scoped to\nyour company. Mirrors the `PATCH /api/v1/bonuses/:id` endpoint.\n\nInputs:\n- `id` (string) — the recognition's BSON ObjectId.\n- `reason` (string) — the NEW, complete recognition message. This REPLACES\n  the entire reason, so include the `+amount`, `@mentions`, and `#hashtag`\n  you want to keep (e.g. \"+50 @jane.doe Updated message #teamwork\"). Omitting\n  them drops them from the recognition.\n\nWhen any required input is missing the response either carries a\n`requestedSchema` (for clients that declared `elicitation`) or a standard\n`INVALID_PARAMS` error.\n\nEditing is only permitted for recognition you gave/initiated, within\n24 hours of creation, and only when the\npoints haven't already been spent. Returns the updated recognition on success.\n","inputSchema":{"type":"object","properties":{"id":{"type":"string","description":"The recognition's BSON ObjectId."},"reason":{"type":"string","description":"The new, complete recognition message (replaces the existing reason)."}},"required":["id"],"additionalProperties":false,"strict":true},"outputSchema":{"type":"object","properties":{"id":{"type":"string"},"parent_bonus_id":{},"created_at":{"type":"string"},"reason":{"type":"string"},"amount":{"type":"integer"},"family_amount":{"type":"integer"},"hashtag":{"type":"string"},"giver":{"type":"object","properties":{"id":{"type":"string"},"display_name":{"type":"string"}},"required":["id","display_name"]},"receiver":{"type":"object","properties":{"id":{"type":"string"},"display_name":{"type":"string"}},"required":["id","display_name"]},"receivers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"display_name":{"type":"string"}},"required":["id","display_name"]}}},"required":["id","created_at","reason","amount","family_amount","hashtag","giver","receiver","receivers"]},"annotations":{"readOnlyHint":false}}],"protocol_methods":["elicitation/create","initialize","ping","prompts/list","resources/list","tools/call","tools/list"]}