---
title: "Call a tool by its name"
method: POST
path: "/api/v1/tools/{name}"
tags: ["Integrations"]
---

# Call a tool by its name

`POST /api/v1/tools/{name}`

## Request

- Base URL: `https://api.custodo.ai`
- URL: `https://api.custodo.ai/api/v1/tools/{name}`
- Auth: HTTP bearer

Every operation in this reference, by the tool’s name instead of its REST address: the arguments are one JSON object in the body — path, query and body fields alike — and the call is the one an AI assistant makes over MCP, with the same permission, the same limits and the same audit. Reads too.

The answer differs from the REST routes in one way: a tool that ran and refused is a 200 with `is_error: true` and its reason in `result`, as over MCP, instead of an HTTP error.

## Path parameters

- `name` 'custodo_whoami' | 'custodo_manual' | 'custodo_list_tenants' | 'custodo_switch_tenant' | 'custodo_list_todos' | 'custodo_query_analytics' | 'custodo_search_audit' | 'custodo_list_members' | 'custodo_list_teams' | 'custodo_get_module_settings' | 'custodo_view_link' | 'custodo_list_views' | 'custodo_save_view' | 'custodo_delete_view' | 'documents_search' | 'documents_get' | 'documents_get_content' | 'documents_download_link' | 'documents_list_types' | 'documents_upload' | 'documents_update_metadata' | 'documents_set_legal_hold' | 'documents_delete' | 'documents_facets' | 'documents_list_views' | 'documents_update' | 'documents_add_version' | 'documents_convert_to_pdf' | 'documents_reprocess' | 'documents_create_type' | 'documents_update_type' | 'documents_delete_type' | 'documents_list_labels' | 'documents_create_label' | 'documents_update_label' | 'documents_delete_label' | 'documents_set_labels' | 'documents_bulk_labels' | 'documents_list_links' | 'documents_link' | 'documents_unlink' | 'conservazione_list_packages' | 'conservazione_get_package' | 'conservazione_verify_package' | 'conservazione_list_versamenti' | 'conservazione_get_status' | 'conservazione_request_dip' | 'conservazione_set_class' | 'anagrafiche_search_parties' | 'anagrafiche_get_party' | 'anagrafiche_get_dossier' | 'anagrafiche_list_links' | 'anagrafiche_list_roles' | 'anagrafiche_find_duplicates' | 'anagrafiche_create_party' | 'anagrafiche_update_party' | 'anagrafiche_delete_party' | 'anagrafiche_set_address' | 'anagrafiche_delete_address' | 'anagrafiche_link' | 'anagrafiche_unlink' | 'anagrafiche_remove_match' | 'anagrafiche_restore_match' | 'anagrafiche_bulk_document_links' | 'anagrafiche_analyse_spreadsheet' | 'anagrafiche_import_spreadsheet' | 'tabelle_list_tables' | 'tabelle_get_table' | 'tabelle_search_rows' | 'tabelle_create_row' | 'tabelle_update_row' | 'tabelle_delete_row' | 'tabelle_create_table' | 'tabelle_update_table' | 'email_search' | 'email_get' | 'email_list_accounts' | 'email_draft' | 'email_send' | 'email_label' | 'email_list_labels' | 'email_create_label' | 'email_update_label' | 'email_delete_label' | 'email_sync_account' | 'email_list_outbox' | 'email_get_outbox' | 'email_update_draft' | 'email_discard_draft' | 'email_undo_send' | 'email_get_thread' | 'email_counts' | 'email_set_flags' | 'email_bulk' | 'email_delete_message' | 'email_list_contacts' | 'email_download_link' | 'email_attach' | 'email_archive_attachment' | 'email_archive_message' | 'whatsapp_list_accounts' | 'whatsapp_list_chats' | 'whatsapp_get_chat' | 'whatsapp_send_message' | 'protocolli_list_protocols' | 'protocolli_get_protocol' | 'protocolli_list_register' | 'protocolli_find_record' | 'protocolli_create_protocol' | 'protocolli_update_protocol' | 'protocolli_set_status' | 'protocolli_register' | 'protocolli_update_entry' | 'protocolli_decide_suggestion' | 'protocolli_cancel_entry' | 'protocolli_cancel_protocol' | 'workflow_list_tasks' | 'workflow_get_instance' | 'workflow_list_flows' | 'workflow_start' | 'workflow_decide' | 'workflow_comment' | 'workflow_claim_task' | 'workflow_reassign_task' | 'workflow_cancel_instance' | 'workflow_list_instances' | 'workflow_stats' | 'workflow_run_counts' | 'workflow_subject_status' | 'workflow_list_delegations' | 'workflow_create_delegation' | 'workflow_revoke_delegation' | 'workflow_get_flow' | 'workflow_list_actions' | 'workflow_task_comment' | 'workflow_create_flow' | 'workflow_update_flow' | 'attivita_list_tasks' | 'attivita_get_task' | 'attivita_list_lists' | 'attivita_create_task' | 'attivita_update_task' | 'attivita_set_status' | 'attivita_assign_task' | 'attivita_bulk_update' | 'attivita_add_checklist_item' | 'attivita_update_checklist_item' | 'attivita_add_comment' | 'attivita_attach_document' | 'attivita_link_messages' | 'checklist_list_checklists' | 'checklist_get_checklist' | 'checklist_create_checklist' | 'checklist_update_checklist' | 'checklist_duplicate_checklist' | 'checklist_update_cell' | 'checklist_update_cells' | 'checklist_list_statuses' | 'checklist_set_cell_note' | 'checklist_add_comment' | 'checklist_add_document' | 'calendario_list_events' | 'calendario_get_event' | 'calendario_list_calendars' | 'calendario_list_deadlines' | 'calendario_create_event' | 'calendario_update_event' | 'calendario_respond_event' | 'calendario_delete_event' | 'crm_list_deals' | 'crm_get_deal' | 'crm_list_activities' | 'crm_create_lead' | 'crm_log_activity' | 'crm_advance_deal' | 'crm_list_lookups' | 'crm_create_deal' | 'crm_update_deal' | 'crm_delete_deal' | 'crm_bulk_deals' | 'crm_reopen_deal' | 'crm_convert_lead' | 'crm_get_deal_history' | 'crm_deals_board' | 'crm_update_activity' | 'crm_complete_activity' | 'crm_delete_activity' | 'crm_get_timeline' | 'crm_create_pipeline' | 'crm_update_pipeline' | 'crm_delete_pipeline' | 'crm_set_stage' | 'crm_delete_stage' | 'crm_reorder_stages' | 'crm_set_lost_reason' | 'crm_delete_lost_reason' | 'crm_list_attachments' | 'crm_attach_document' | 'crm_detach_document' | 'crm_analyse_spreadsheet' | 'crm_import_spreadsheet' | 'crm_export_spreadsheet' | 'spese_list_expenses' | 'spese_get_expense' | 'spese_list_categories' | 'spese_list_channels' | 'spese_list_reports' | 'spese_get_report' | 'spese_create_expense' | 'spese_update_expense' | 'spese_create_report' | 'spese_update_report' | 'spese_attach_to_report' | 'spese_remove_from_report' | 'spese_submit_report' | 'spese_reimburse_report' | 'timbratura_list_employees' | 'timbratura_get_presence' | 'timbratura_list_stamps' | 'timbratura_get_timesheet' | 'timbratura_list_anomalies' | 'timbratura_list_leave_requests' | 'timbratura_get_balances' | 'timbratura_list_corrections' | 'timbratura_list_posts' | 'timbratura_list_sites' | 'timbratura_list_schedules' | 'timbratura_list_absence_types' | 'timbratura_request_leave' | 'timbratura_decide_leave' | 'timbratura_cancel_leave' | 'timbratura_create_closure' | 'timbratura_decide_correction' | 'timbratura_add_stamp' | 'timbratura_update_stamp' | 'timbratura_justify_anomaly' | 'timbratura_add_balance_entry' | 'timbratura_create_post' | 'timbratura_update_post' | 'timbratura_update_profile' | 'timbratura_assign_schedule' | 'timbratura_create_site' | 'timbratura_update_site' | 'firme_list_envelopes' | 'firme_get_envelope' | 'firme_download_link' | 'firme_create_envelope' | 'firme_update_envelope' | 'firme_send_envelope' | 'firme_void_envelope' | 'raccolta_list_collections' | 'raccolta_get_collection' | 'raccolta_list_requests' | 'raccolta_create_collection' | 'raccolta_add_recipients' | 'raccolta_send_collection' | 'raccolta_remind_request' | 'raccolta_mark_received' | 'condivisione_list_shares' | 'condivisione_get_share' | 'condivisione_list_recipients' | 'condivisione_preview_share' | 'condivisione_create_share' | 'condivisione_update_share' | 'condivisione_send_share' | 'condivisione_cancel_share' | 'condivisione_withdraw_share' | 'condivisione_list_schedules' | 'condivisione_create_schedule' | 'condivisione_update_schedule' | 'integrazioni_list_calls' | 'integrazioni_list_usage' | 'integrazioni_list_webhooks' | 'integrazioni_list_deliveries' | 'agenti_list' | 'agenti_run' | 'agenti_list_runs' | 'agenti_get_run' | 'bi_list_dashboards' | 'bi_get_dashboard' | 'bi_run_dashboard' | 'bi_create_dashboard' | 'bi_update_dashboard' | 'ordini_list_orders' | 'ordini_get_order' | 'ordini_search_articles' | 'ordini_create_order' | 'ordini_update_order' | 'ordini_set_lines' | 'ordini_set_status' | 'ordini_confirm_order' | 'ordini_add_comment' | 'ordini_link_messages' | 'ordini_upsert_article' | 'notifiche_list_inbox' | 'notifiche_counts' | 'notifiche_mark_read', required

## Headers

- `X-Tenant-Id` string, uuid

## Request body

- object: The tool’s arguments, as its REST operation describes them.

## Response `200`

The tool ran. `is_error: true` means it ran and refused — a document under legal hold, a deal already closed. Fix the arguments, do not retry blindly.

- ToolResult
  - `ok` true, required
  - `data` object, required
    - `result` unknown, required
    - `is_error` boolean, required: True when the tool ran and refused. The refusal is inside `result`.
    - `resource_links` object[]: Handles to things the answer refers to, when there are any.
      - `uri` string
      - `name` string
      - `mimeType` string, nullable

## Other responses

- `403`: The call never happened: the module is off for this organisation, the credential lacks the scope, the tier does not cover it, or the tool is destructive and the key was not minted for that.
- `404`: No tool by that name in this build.
- `429`: The credential has spent its minute, or its day. See `Retry-After`.

---

[API](https://skmtc.dev/custodo/apis/custodo-integrazioni.md) · [All operations](https://skmtc.dev/custodo/apis/custodo-integrazioni/llms.txt) · [OpenAPI document](https://skmtc.dev/custodo/apis/custodo-integrazioni/revisions/16d336d3ec2a?raw)