@trylighthouse/mcp-server 0.2.15 → 0.2.17

package/build/server.js

@@ -81,11 +81,15 @@ const ADDRESS_INPUT = z.union([
     }),
 ]);
 const RECIPIENTS = z.union([ADDRESS_INPUT, z.array(ADDRESS_INPUT)]);
+const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const CREATES = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+const ADDS_IF_MISSING = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false };
 export function createServer(apiKey, options = {}) {
     const api = new LighthouseAPI(apiKey);
     const server = new McpServer({
         name: "lighthouse",
-        version: "0.2.15",
+        version: "0.2.17",
     });
     const originalRegister = server.registerTool.bind(server);
     server.registerTool = (name, schemaOrConfig, handler) => {
@@ -259,6 +263,7 @@ export function createServer(apiKey, options = {}) {
         "(an outer AND of two OR groups; country codes from list_locations).";
     server.registerTool("lighthouse_crm_list_attributes", {
         title: "List CRM Attributes",
+        annotations: READ_ONLY,
         description: "Get a lightweight catalog of the fields for a CRM record type: each field's permalink, label, data_type, links_to, read_only, is_custom, has_options, source_field and list_id. " +
             "`source_field` names the status attribute a `duration` attribute is derived from (null on every other attribute); such attributes (time_in_stage on deals, time_in_status on tasks, time_in_<status> beside a custom status field) are read-only and computed, never written. " +
             "ALWAYS call this before building filters for search_records / list_records or creating/updating views. Use the exact permalinks it returns. " +
@@ -292,6 +297,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_get_attribute", {
         title: "Get CRM Attribute",
+        annotations: READ_ONLY,
         description: "Get a single custom field definition. Response returns 'permalink', 'is_custom', 'data_type', 'links_to'. " +
             "For custom objects, use the object's permalink as record_type (e.g. 'lp').",
         inputSchema: {
@@ -309,6 +315,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_create_attribute", {
         title: "Create CRM Attribute",
+        annotations: CREATES,
         description: "Create a new custom field in your CRM workspace. " +
             "Types: text, number, currency, percentage, date, datetimez, select, multi_select, status, checkbox, url, email, phone, rating, record, multi_record, user, multi_user. " +
             "Supports custom objects, use the object's permalink as record_type (e.g. 'lp'). " +
@@ -360,6 +367,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_update_attribute", {
         title: "Update CRM Attribute",
+        annotations: DESTRUCTIVE,
         description: "Update a custom field's display label (the field type, linked record type, and options are fixed after creation). " +
             "For custom objects, use the object's permalink as record_type.",
         inputSchema: {
@@ -379,6 +387,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_delete_attribute", {
         title: "Delete CRM Attribute",
+        annotations: DESTRUCTIVE,
         description: "Delete a custom field and all its data. Only custom fields can be deleted, not system fields. " +
             "For custom objects, use the object's permalink as record_type.",
         inputSchema: {
@@ -396,6 +405,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_list_colors", {
         title: "List Colors",
+        annotations: READ_ONLY,
         description: "Get the available color palette for select/multi_select/status field options. " +
             "Returns an array of {hex_code, label} objects. " +
             "Use this to discover valid hex color codes when creating or updating select options.",
@@ -411,6 +421,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_list_options", {
         title: "List CRM Field Options",
+        annotations: READ_ONLY,
         description: "Get the allowed values for a CRM select / multi_select field. Each row is { value, label, color, priority, is_default, enabled }, the same object the options[] of an attribute carries; a built-in value the workspace switched off is listed with enabled: false rather than left out, so do not offer it when setting a field. " +
             "Call this when lighthouse_crm_list_attributes shows has_options=true for a field and you need its values before filtering or setting it. " +
             "Results are paginated (max 100 per page): use `search` to narrow by label, and `limit` / `offset` to page through a field with many options. " +
@@ -434,6 +445,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_create_option", {
         title: "Create CRM Field Option",
+        annotations: CREATES,
         description: "Add a new option to a select/multi_select field. The option value is auto-generated from the label. " +
             "Re-creating a system default option that was previously removed restores it (its original color and label are kept). " +
             "Returns the updated list of ALL options for the field, each row { value, label, color, priority, is_default, enabled }, with a switched-off built-in value listed as enabled: false, plus meta.total. The list comes back in the order the field offers its options, so do not read the first row as the option you just created: find it by the label you sent. " +
@@ -457,6 +469,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_delete_option", {
         title: "Delete CRM Field Option",
+        annotations: DESTRUCTIVE,
         description: "Delete an option value from a select/multi_select field. Custom options are removed permanently; a system default option is disabled for the workspace instead (re-create it to restore). " +
             "For custom objects, use the object's permalink as record_type.",
         inputSchema: {
@@ -475,6 +488,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_search_records", {
         title: "Search CRM Records",
+        annotations: READ_ONLY,
         description: "Search and filter records in YOUR CRM workspace (companies, people, or deals you've added). " +
             "Supports filters, sorting, pagination, and saved views. " +
             "A search by MEANING over people or company records is a semantic_search condition in filters; it needs the ready vector of a saved view (lighthouse_crm_get_view) or of a condition copied from the app, never text and never a vector you wrote (the filters description has the rule). " +
@@ -520,6 +534,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_get_record", {
         title: "Get CRM Record",
+        annotations: READ_ONLY,
         description: "Get a single CRM record by ID with all fields and relationships. Custom fields are returned as top-level keys, not nested under an attributes object. " +
             "Signal fields (company_signals on companies, person_signals on people) are arrays of signal objects, one per signal: { signal (the value), picked_up_on (ISO 8601 date, the day the feed picked it up), occurrences (the number of windows or registrations behind it, 1 otherwise), and what the feed knows: " +
             "for a company measured_on, timeframe, change_percent, value (the metric's value on measured_on, from the most recently measured window), windows (every window, each its own snapshot: [{timeframe, change_percent, value, measured_on, picked_up_on}]), money_raised_usd, investment_type, announced_on, investment_stage, num_investors, pre_money_valuation_usd; " +
@@ -546,6 +561,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_list_record_activity", {
         title: "List Record Activity",
+        annotations: READ_ONLY,
         description: "Read the activity feed of one CRM record, newest first: who changed what, when, and from where. Use it to answer questions about history (\"what changed on this deal last week\", \"who moved it to won\", \"which fields has nobody touched\") instead of guessing from the record's current values. " +
             "Each entry has: action (created / updated / deleted / merged), occurred_at, summary (a ready-made sentence, ending \"via <the source>\" when a workflow or an API key made the change rather than a person, since both log a human as the actor), target ({ record_type, id, name }; the feed also carries the notes and tasks attached to the record, so the target is not always the record itself), actor (null for automated changes), and source. " +
             "source always has { type, label }: type is app / mobile / api / mcp / workflow / ai_assistant / notetaker / email_sync / calendar_sync / linkedin_sync / inbound_email / inbound_whatsapp / scout / lp_portal / sync, and label names the exact origin. The four trace keys are always present and null when the origin did not record them: workflow is { id, name, run_id, node_id } when a workflow made the change (tracing an entry back to the exact run and step), api_key_id / mcp_tool identify the key or AI tool behind an API change, and trigger is automatic or manual where the origin recorded whether a person asked for the change (meeting notes written on their own and notes a member asked for both log that member as the actor, so trigger is what tells them apart). " +
@@ -573,6 +589,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_list_ai_reports", {
         title: "List AI Reports on a Record",
+        annotations: READ_ONLY,
         description: "The AI reports generated on one CRM record (any record type: company, person, deal, or a custom object permalink), newest first: the memos, SWOTs, teardowns, pass memos and briefs a member generated from the record's AI Reports tab in Lighthouse. " +
             "WHEN TO USE: the user asks whether a memo or report already exists on a record, what the last one said, wants to compare or build on an earlier report, or asks about a company's \"memo\" / \"analysis\" / \"write-up\" (check here before writing one from scratch). Not for dashboards or charts (those are lighthouse_reports_*), and nothing here generates a report: that happens in the app. " +
             "Each row: id, name, status (processing / success / error), depth (short / standard / extensive), template, partial (true when the run hit a cap), summary (one paragraph of the report's own prose), created_by ({ id, first_name, last_name, full_name, avatar_url, email }, the same member object every other row carries), created_at, completed_at. Only a success report has a document: read it with lighthouse_crm_get_ai_report. " +
@@ -596,6 +613,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_get_ai_report", {
         title: "Get AI Report",
+        annotations: READ_ONLY,
         description: "One AI report by id (from lighthouse_crm_list_ai_reports): the same metadata plus record_type / record_id and content, the full document as Markdown with its section headings (citation markers removed). " +
             "WHEN TO USE: the user wants what an earlier memo or report actually says (a section, a number, a recommendation), or a comparison with it. A report can be long: quote or summarise the part the question is about rather than echoing it whole. " +
             "content is null while the report is still processing or failed. Answers 403 naming the channel when the report draws on a shared mailbox, calendar, meeting notes, LinkedIn account or document the API key's user cannot read, or on " + REPORT_ROLE_SOURCES + " (its author is never refused for its sources), and 404 for an unknown id.",
@@ -613,6 +631,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_create_record", {
         title: "Create CRM Record",
+        annotations: CREATES,
         description: "Create a new CRM record. Pass all fields (standard + custom) in a single flat data object, " +
             "the API splits standard vs custom fields automatically. " +
             "BEFORE calling this tool, call lighthouse_crm_list_attributes to discover available field keys and types for the record_type. " +
@@ -647,6 +666,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_update_record", {
         title: "Update CRM Record",
+        annotations: DESTRUCTIVE,
         description: "Update an existing CRM record. Only include the fields you want to change. " +
             "Standard and custom fields can be mixed in a single flat data object, the API splits them automatically. " +
             "BEFORE calling this tool, call lighthouse_crm_list_attributes to discover available field keys and types. " +
@@ -684,6 +704,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_upsert_record", {
         title: "Upsert CRM Record",
+        annotations: DESTRUCTIVE,
         description: "Find-or-create a CRM record by a UNIQUE attribute: if a record already matches the value it is updated, otherwise a new one is created. " +
             "Only person and company support upsert, person matches on email or linkedin, company on domain or linkedin (set matching_attribute accordingly). " +
             "Pass the value to match on as `matching_value` (\"jane@acme.com\", \"acme.com\", a LinkedIn address). It may also sit inside data as the attribute itself (emails: [\"jane@acme.com\"], domain: [\"acme.com\"], linkedin: \"...\"), which is what this tool used to require; matching_value wins when both carry it, and a request with neither is refused. A record created this way still stores the value. " +
@@ -711,6 +732,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_delete_record", {
         title: "Delete CRM Record",
+        annotations: DESTRUCTIVE,
         description: "Permanently delete a CRM record. For custom objects, use the object's permalink as record_type.",
         inputSchema: {
             record_type: z.string().describe("Record type: company, person, deal, or a custom object permalink"),
@@ -727,6 +749,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_bulk_create_records", {
         title: "Bulk Create CRM Records",
+        annotations: CREATES,
         description: "Create up to 100 CRM records of the same record_type in one call. " +
             "Each item in `records` is a flat data object, the SAME shape you'd pass as `data` to lighthouse_crm_create_record. " +
             "BEFORE calling, call lighthouse_crm_list_attributes to discover field keys and types. " +
@@ -752,6 +775,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_bulk_update_records", {
         title: "Bulk Update CRM Records",
+        annotations: DESTRUCTIVE,
         description: "Update up to 100 CRM records of the same record_type in one call. " +
             "Each item in `records` is { id, data }, `id` is the record UUID and `data` is a flat object of the fields to change " +
             "(same shape as lighthouse_crm_update_record). " +
@@ -779,6 +803,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_bulk_upsert_records", {
         title: "Bulk Upsert CRM Records",
+        annotations: DESTRUCTIVE,
         description: "Find-or-create up to 100 records of the same record_type in one call, each matched on a unique attribute. " +
             "For each item, if a record already matches the value it is updated, otherwise a new one is created. " +
             "Person matches on email or linkedin, company on domain or linkedin (set matching_attribute for the whole batch). " +
@@ -808,6 +833,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_bulk_delete_records", {
         title: "Bulk Delete CRM Records",
+        annotations: DESTRUCTIVE,
         description: "Permanently delete up to 100 CRM records of the same record_type in one call. " +
             "Pass `ids` as an array of record UUIDs. " +
             "Partial success: the response returns a `results` array (one entry per id, in order, with success/error) and a `summary` ({total, succeeded, failed}).",
@@ -826,6 +852,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_create_list", {
         title: "Create CRM List",
+        annotations: CREATES,
         description: "Create a new CRM list to organize records. Supports companies, people, deals, and custom objects. " +
             "Defaults to 'private' visibility. " +
             "To share with specific teams after creation, use lighthouse_crm_share_list_with_teams. " +
@@ -847,6 +874,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_list_lists", {
         title: "List CRM Lists",
+        annotations: READ_ONLY,
         description: "Get all CRM lists in your workspace. Each list's record_type is 'company', 'person', 'deal', or a custom object permalink (e.g. 'lp', 'project'), and that is the record type of everything in it. " +
             "Each row carries owner (the member who created it) and is_owner (true when that member is the API key's user), so 'my lists' and 'lists shared with me' can be told apart without a second call. " +
             "WHEN TO USE: to find a list someone names (\"the Deals Reviewed list\"), pass search with the words of its name and read the id off the matching row, instead of paging through every list; leave search out to page through all of them. meta.total counts the lists that matched.",
@@ -867,6 +895,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_get_list", {
         title: "Get CRM List",
+        annotations: READ_ONLY,
         description: "Get a single CRM list by ID with its configuration. Its record_type is 'company', 'person', 'deal', or a custom object permalink (e.g. 'lp', 'project'). " +
             "is_owner says whether the API key's user owns the list, so 'my lists' and 'lists shared with me' can be told apart without a second call. A list you cannot open answers 'List not found', the same as one that does not exist.",
         inputSchema: {
@@ -884,6 +913,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_update_list", {
         title: "Update CRM List",
+        annotations: DESTRUCTIVE,
         description: "Update a CRM list's name or configuration. A list you cannot open answers 'List not found', the same as one that does not exist.",
         inputSchema: {
             list_id: z.string().uuid().optional().describe("List ID"),
@@ -904,6 +934,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_delete_list", {
         title: "Delete CRM List",
+        annotations: DESTRUCTIVE,
         description: "Permanently delete a CRM list. A list you cannot open answers 'List not found', the same as one that does not exist.",
         inputSchema: {
             list_id: z.string().uuid().optional().describe("List ID"),
@@ -920,6 +951,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_list_list_records", {
         title: "List Records in a List",
+        annotations: READ_ONLY,
         description: "Get records in a CRM list with optional filtering, sorting, and view support. " +
             "Same filter format as lighthouse_crm_search_records. To get valid filter keys, call lighthouse_crm_list_attributes with this list's record_type, which is 'company', 'person', 'deal', or a custom object permalink. " +
             "The response's `meta` includes `total` (an integer match count), `ignored_filter_fields` (any filter key that is not a valid attribute for this list's record type, each with a did_you_mean suggestion when a close match can be computed), `invalid_operators` (a condition whose operator its field does not take, left out of the results), `invalid_logical_operators` (a group joined by something other than AND/OR, read as AND) and `invalid_sort_fields` (a sort this list cannot apply, reported rather than refused, so the records come back in their default order). The saved filters of a view_id are reported on the same way. Check every array to confirm the whole filter and the sort were applied; a value in the wrong shape is refused instead, with a 400. " +
@@ -946,6 +978,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_add_to_list", {
         title: "Add Record to List",
+        annotations: ADDS_IF_MISSING,
         description: "Add a CRM record to a list. The record type is inferred from the list, so the record must be of the list's record_type: 'company', 'person', 'deal', or a custom object permalink. Answers `reason` beside the flag: the sentence \"This record was already on the list.\" / \"This record was not on the list.\" when the call changed nothing, and null when it did. Both writes succeed either way, so this key is what tells a no-op from a real change.",
         inputSchema: {
             list_id: z.string().uuid().describe("List ID"),
@@ -964,6 +997,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_remove_from_list", {
         title: "Remove Record from List",
+        annotations: DESTRUCTIVE,
         description: "Remove a record from a CRM list. The record type is inferred from the list, whose record_type is 'company', 'person', 'deal', or a custom object permalink. Answers `reason` beside the flag: the sentence \"This record was already on the list.\" / \"This record was not on the list.\" when the call changed nothing, and null when it did. Both writes succeed either way, so this key is what tells a no-op from a real change.",
         inputSchema: {
             list_id: z.string().uuid().describe("List ID"),
@@ -980,6 +1014,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_bulk_add_to_list", {
         title: "Bulk Add Records to List",
+        annotations: ADDS_IF_MISSING,
         description: "Add up to 100 CRM records to a list in one call. The record type is inferred from the list, so every id must be of the list's record_type: 'company', 'person', 'deal', or a custom object permalink. " +
             "Partial success: the response returns a `results` array (one entry per id, in order, with success/error) and a `summary` ({total, succeeded, failed}). " +
             "A failed id does NOT prevent the others from being added. Every result entry also carries `reason`, ONE key for \"why did this record not change\": the no-op sentence on a success that wrote nothing, the refusal in words on a failure, null when the record really changed. `error` stays beside it for a client that branches on a code.",
@@ -998,6 +1033,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_bulk_remove_from_list", {
         title: "Bulk Remove Records from List",
+        annotations: DESTRUCTIVE,
         description: "Remove up to 100 CRM records from a list in one call. Every id must be of the list's record_type: 'company', 'person', 'deal', or a custom object permalink. " +
             "Partial success: the response returns a `results` array (one entry per id, in order, with success/error) and a `summary` ({total, succeeded, failed}). Every result entry also carries `reason`, ONE key for \"why did this record not change\": the no-op sentence on a success that wrote nothing, the refusal in words on a failure, null when the record really changed. `error` stays beside it for a client that branches on a code.",
         inputSchema: {
@@ -1015,6 +1051,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_share_list_with_teams", {
         title: "Share List with Teams",
+        annotations: ADDS_IF_MISSING,
         description: "Grant team-level access to a CRM list. Only the list owner can share. " +
             "Use lighthouse_workspace_list_teams to find team IDs first. " +
             "Requires lists.share permission. " +
@@ -1036,6 +1073,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_revoke_list_from_teams", {
         title: "Revoke List Team Access",
+        annotations: DESTRUCTIVE,
         description: "Revoke team-level access from a CRM list. Only the list owner can revoke. " +
             "Requires lists.share permission. " +
             "Returns formatted list: {id, name, record_type, sharing, color, count, owner, is_owner, shared_with_teams, created_at, updated_at}, where record_type is 'company', 'person', 'deal', or a custom object permalink and is_owner says whether the API key's user owns the list.",
@@ -1056,6 +1094,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_update_list_sharing", {
         title: "Update List Sharing Status",
+        annotations: DESTRUCTIVE,
         description: "Change a CRM list's sharing visibility. Setting to 'private' also removes all team permissions. " +
             "Only the list owner can change sharing. Requires lists.share permission. " +
             "Returns formatted list: {id, name, record_type, sharing, color, count, owner, is_owner, shared_with_teams, created_at, updated_at}, where record_type is 'company', 'person', 'deal', or a custom object permalink and is_owner says whether the API key's user owns the list.",
@@ -1076,6 +1115,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_list_notes", {
         title: "List Notes",
+        annotations: READ_ONLY,
         description: "Get notes for a CRM record. Each note in the response includes a `records` map, every record (company/person/deal/custom object) the note is currently linked to that you can view, plus a `tags` array of any workspace tags attached to the note (each with id, label, color). " +
             LINKED_RECORDS_LEFT_OUT + " " +
             "`tagged_users` is the teammates the note MENTIONS, each the member object this API answers for a person ({ id, first_name, last_name, full_name, avatar_url, email }), and [] when it mentions nobody. It is read from the mention spans in `content`, not from the ids a write sent, so a note written with tagged_users ids and no mention span reads back []: always write both, as lighthouse_crm_create_note and lighthouse_crm_update_note say. " +
@@ -1096,6 +1136,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_search_notes", {
         title: "Search Notes",
+        annotations: READ_ONLY,
         description: "Search ALL notes in the workspace (unlike List Notes, which needs one record). Combine a free-text title search with a CRM-style filter tree and sort. " +
             'filters: {"operator":"AND","conditions":[{"field":"tags","operator":"contains_any","value":["<tag_permalink>"]}]}: nested groups supported. ' +
             "Filterable fields and their operators: title (text: contains/not_contains/starts_with/ends_with/eq/neq/empty/not_empty), " +
@@ -1125,6 +1166,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_create_note", {
         title: "Create Note",
+        annotations: CREATES,
         description: "Create a note, optionally linked to one or more CRM records. Records are optional: omit them to create a standalone note that still appears in the workspace Notes section. " +
             "Link records via the `records` param, keyed by type. " +
             "The company/person/deal ids you pass MUST be EXISTING CRM record ids (the ids returned by lighthouse_crm_* tools), NOT discovery ids from lighthouse_discovery_* search results. To note on a discovery result, first add it to your CRM and use the resulting CRM record id. " +
@@ -1164,6 +1206,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_get_note", {
         title: "Get Note",
+        annotations: READ_ONLY,
         description: "Get a single note by ID. Response includes a `records` object keyed by record type (or custom object permalink) with every linked record you can view, plus a `tags` array of any workspace tags attached to the note (each with permalink, label, color). " +
             LINKED_RECORDS_LEFT_OUT + " " +
             "`tagged_users` is the teammates the note MENTIONS, each the member object this API answers for a person ({ id, first_name, last_name, full_name, avatar_url, email }), and [] when it mentions nobody. It is read from the mention spans in `content`, not from the ids a write sent, so a note written with tagged_users ids and no mention span reads back []: always write both, as lighthouse_crm_create_note and lighthouse_crm_update_note say. " +
@@ -1183,6 +1226,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_update_note", {
         title: "Update Note",
+        annotations: DESTRUCTIVE,
         description: "Change an existing note's title, content, tags or mentions by note ID. Pass only what changes: a key that is absent is left untouched. " +
             "content REPLACES the whole body: to ADD to a note, read it with lighthouse_crm_get_note first and pass the full new content with the addition, never the addition alone (anything you leave out, an existing @mention span included, is gone). " +
             "Content is HTML, the same format lighthouse_crm_create_note takes: <p> for paragraphs, <ul><li> for bullets, <h2> for a heading, <strong> for emphasis; plain text works too and is stored as one paragraph. " +
@@ -1211,6 +1255,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_delete_note", {
         title: "Delete Note",
+        annotations: DESTRUCTIVE,
         description: "Permanently delete a note and all of its record links. Meeting notes are deleted the same way, together with every version of them; the meeting's recording and transcript are not affected.",
         inputSchema: {
             note_id: z.string().uuid().optional().describe("Note ID"),
@@ -1227,6 +1272,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_link_note_record", {
         title: "Link Record to Note",
+        annotations: ADDS_IF_MISSING,
         description: "Attach a record to an existing note. Call once per record. " +
             "The company/person/deal record_id MUST be an EXISTING CRM record id (an id returned by lighthouse_crm_* tools), NOT a discovery id from lighthouse_discovery_* search results. To link a discovery result, first add it to your CRM and use the resulting CRM record id. " +
             LINK_NOT_VIEWABLE_RULE + " " +
@@ -1247,6 +1293,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_unlink_note_record", {
         title: "Unlink Record from Note",
+        annotations: DESTRUCTIVE,
         description: "Remove a record link from a note. Call once per record. " +
             "Removing the last linked record is allowed and leaves a standalone note (it stays in the workspace Notes section). " +
             UNLINK_NOT_VIEWABLE_KEPT,
@@ -1266,6 +1313,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_list_note_tags", {
         title: "List Note Tags",
+        annotations: READ_ONLY,
         description: "List the workspace's note tags: labeled, colored tags that can be attached to notes as a multi-select. " +
             "Returns an array of { permalink, label, color }. " +
             "Use this to find tag permalinks before attaching them to a note (via lighthouse_crm_create_note `tags` or lighthouse_crm_manage_note_tags). " +
@@ -1282,6 +1330,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_create_note_tag", {
         title: "Create Note Tag",
+        annotations: CREATES,
         description: "Create a new note tag in the workspace vocabulary. The tag can then be attached to notes. " +
             "Returns the created tag as { permalink, label, color }. " +
             "Color is an optional palette code (get available colors from lighthouse_crm_list_colors); omit it to auto-assign one.",
@@ -1300,6 +1349,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_update_note_tag", {
         title: "Update Note Tag",
+        annotations: DESTRUCTIVE,
         description: "Update a note tag's label and/or color. Only the fields you pass are changed. " +
             "Returns the updated tag as { permalink, label, color }.",
         inputSchema: {
@@ -1318,6 +1368,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_delete_note_tag", {
         title: "Delete Note Tag",
+        annotations: DESTRUCTIVE,
         description: "Delete a note tag from the workspace vocabulary. The tag is also detached from any notes it was attached to.",
         inputSchema: {
             permalink: z.string().describe("Tag permalink"),
@@ -1333,6 +1384,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_manage_note_tags", {
         title: "Attach or Detach Note Tags",
+        annotations: DESTRUCTIVE,
         description: "Attach or detach workspace tags on an existing note. Pass operation ADD to attach the tag permalinks, or REMOVE to detach them. " +
             "Find tag permalinks with lighthouse_crm_list_note_tags. Returns the updated note (including its current `tags`).",
         inputSchema: {
@@ -1353,6 +1405,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_list_tasks", {
         title: "List Tasks",
+        annotations: READ_ONLY,
         description: "List CRM tasks with optional filtering and sorting. " +
             'filters (CRM-style): {"operator":"AND","conditions":[{"field":"status","operator":"contains_any","value":["<status_value>"]}]} (status AND priority are option fields whose values are workspace-specific; fetch them with lighthouse_crm_list_options(record_type:\'task\', permalink:\'status\' | \'priority\'), and filter priority with contains_any like status, not with a numeric comparison); ' +
             'sort: [{"field":"due_date","direction":"asc"}]; ' +
@@ -1379,6 +1432,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_get_task", {
         title: "Get Task",
+        annotations: READ_ONLY,
         description: "Get a single CRM task by ID. " +
             "status and priority answer the stored VALUE and nothing else. The words your workspace puts on those values come from lighthouse_crm_list_options(record_type:'task', permalink:'status' | 'priority'), one call that covers every task you will ever read.",
         inputSchema: {
@@ -1395,6 +1449,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_create_task", {
         title: "Create Task",
+        annotations: CREATES,
         description: "Create a CRM task, optionally linked to records and assigned to users. " +
             "Status values are configured per workspace and are NOT fixed: call lighthouse_crm_list_options with record_type 'task' and permalink 'status' to get the allowed values, then pass the option's value (not its label) in `status`. " +
             "status and priority answer the stored VALUE and nothing else. The words your workspace puts on those values come from lighthouse_crm_list_options(record_type:'task', permalink:'status' | 'priority'), one call that covers every task you will ever read.",
@@ -1424,6 +1479,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_update_task", {
         title: "Update Task",
+        annotations: DESTRUCTIVE,
         description: "Update a CRM task. Provide only fields you want to change. " +
             "assigned_to replaces all current assignees. In records, " + TASK_LINKS_PER_TYPE.charAt(0).toLowerCase() + TASK_LINKS_PER_TYPE.slice(1) + " " +
             "Status values are configured per workspace and are NOT fixed: call lighthouse_crm_list_options with record_type 'task' and permalink 'status' to get the allowed values, then pass the option's value (not its label) in `status`. " +
@@ -1456,6 +1512,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_delete_task", {
         title: "Delete Task",
+        annotations: DESTRUCTIVE,
         description: "Permanently delete a CRM task.",
         inputSchema: {
             id: z.string().uuid().describe("Task ID"),
@@ -1471,6 +1528,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_documents_list", {
         title: "List Documents",
+        annotations: READ_ONLY,
         description: "List folders and files at the workspace root, or inside a specific folder. " +
             "Returns { folders, files, breadcrumb } plus meta.folders_next_cursor / " +
             "meta.files_next_cursor for cursor-based pagination. Pass those cursors " +
@@ -1496,6 +1554,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_documents_create_folder", {
         title: "Create Folder",
+        annotations: CREATES,
         description: "Create a folder. At the workspace root, sharing is required. " +
             "Inside a parent folder, sharing is automatically inherited from the parent. " +
             "The folder row comes back with owner (the member who created it, { id, first_name, last_name, full_name, avatar_url, email }), is_owner, my_role, sharing ('private' or 'workspace'), shared_with_teams[] (each { team_id, team_name, role, granted_at }), linked_records_count, created_at and updated_at.",
@@ -1518,6 +1577,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_documents_get_folder", {
         title: "Get Folder",
+        annotations: READ_ONLY,
         description: "WHEN TO USE: the user asks about ONE folder they already know (\"who can see the Investor Updates folder\", \"what is that folder linked to\"), or you have a folder id from lighthouse_documents_list and need its full row. " +
             "Returns the folder itself, not its contents: name, parent_folder_id, sharing ('private' or 'workspace'), shared_with_teams[] (each { team_id, team_name, role, granted_at }), is_owner, my_role ('owner' | 'editor' | 'viewer'), owner ({ id, first_name, last_name, full_name, avatar_url, email }), linked_records_count, linked_records[] (every link you can view, each { record_type, record_id, record_name, avatar_url, created_at }), created_at and updated_at. " +
             "To list what is INSIDE it, call lighthouse_documents_list with this folder_id. A folder you cannot open answers the same not found as one that does not exist.",
@@ -1536,7 +1596,8 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_documents_update_folder", {
         title: "Update Folder",
-        description: "Rename, move, or change sharing on a folder. Editors can rename the folder; only owners can move it, change its sharing, or grant team access. " +
+        annotations: DESTRUCTIVE,
+        description: "Rename, move, or change sharing on a folder. Editors can rename the folder; only owners can move it, change its sharing, or grant team access. A folder that holds files or folders other people own can only be moved down, into a folder below where it is now that you own, with every folder in between yours too; any other move of it answers 403 forbidden. " +
             "Pass team_ids as the full desired list, anything not in the list is revoked. " +
             "Note the two meanings of folder_id across the document tools: here it is the folder being changed, while on lighthouse_documents_update_file it is the folder the file is moved INTO. " +
             "Returns the folder row: owner, is_owner, my_role, sharing, shared_with_teams[] (each { team_id, team_name, role, granted_at }), linked_records_count, created_at, updated_at.",
@@ -1562,6 +1623,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_documents_delete_folder", {
         title: "Delete Folder",
+        annotations: DESTRUCTIVE,
         description: "Restricted to the folder owner. Deletes the folder and its entire subtree only when you own every descendant folder and file. If any descendant is owned by another user, the request is rejected (CANNOT_DELETE_OTHERS_CONTENT_IN_FOLDER) and nothing is deleted. Editors on the folder cannot delete it. Irreversible: there is no recycle bin and the underlying stored files are permanently removed.",
         inputSchema: {
             folder_id: z.string().uuid().describe("Folder UUID"),
@@ -1577,6 +1639,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_documents_link_folder_to_record", {
         title: "Link Folder to Record",
+        annotations: ADDS_IF_MISSING,
         description: "Link a folder to a CRM record, associating the whole folder with the record. The folder then appears on the record (in lighthouse_documents_list_for_record's `folders`); its individual files are not flattened into the record's direct `files` list. " +
             "Answers THE FOLDER itself, the same row lighthouse_documents_get_folder returns (owner, is_owner, my_role, sharing, shared_with_teams[] each { team_id, team_name, role, granted_at }, linked_records_count and linked_records[] as they are after the link), so there is no second call to make.",
         inputSchema: {
@@ -1596,6 +1659,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_documents_unlink_folder_from_record", {
         title: "Unlink Folder from Record",
+        annotations: DESTRUCTIVE,
         description: "Remove a folder→record link. Files inside stop appearing on the record's Files tab. Answers THE FOLDER itself, the same row lighthouse_documents_get_folder returns, with its links as they are after the call.",
         inputSchema: {
             folder_id: z.string().uuid().describe("Folder UUID"),
@@ -1614,6 +1678,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_documents_upload_file", {
         title: "Upload File",
+        annotations: CREATES,
         description: "Reserve a file row and get a signed upload URL: " +
             "1) call this; 2) POST the file to upload_url as multipart/form-data, first append every key/value " +
             "from the returned upload_fields, then append the file last under the field name 'file'. " +
@@ -1641,6 +1706,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_documents_get_file", {
         title: "Get File",
+        annotations: READ_ONLY,
         description: "Get file metadata. Response includes my_role ('owner' | 'editor' | 'viewer'), is_owner, owner (the member who owns it: { id, first_name, last_name, full_name, avatar_url, email }), sharing ('private' or 'workspace'), linked_records_count, linked_records[] and shared_with_teams[] (each entry has { team_id, team_name, role, granted_at }). Pass download_url=true to also receive a short-lived signed read URL (expires in 15 minutes). To read what the file SAYS, use lighthouse_documents_get_file_content.",
         inputSchema: {
             file_id: z.string().uuid().describe("File UUID"),
@@ -1658,6 +1724,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_documents_get_file_content", {
         title: "Read File",
+        annotations: READ_ONLY,
         description: "What one stored file SAYS, as text: PDFs, Word, Excel and PowerPoint files (and their OpenDocument versions), text, CSV and HTML. " +
             "WHEN TO USE: the answer is inside a document the workspace keeps (\"what are the conditions in the term sheet\", \"summarise the memo on this deal\", \"what does the deck say about revenue\"). " +
             "Take the file id from lighthouse_documents_list or lighthouse_documents_list_for_record. " +
@@ -1691,13 +1758,14 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_documents_update_file", {
         title: "Update File",
-        description: "Rename, move, or change sharing on a file. Editors can rename and delete it. Only the owner can move it (into another folder or to the root), change sharing, or grant team access, with one exception: the owner of the folder the file is in can also move it into another folder they own. " +
+        annotations: DESTRUCTIVE,
+        description: "Rename, move, or change sharing on a file. Editors can rename and delete it. Only the owner can move it (into another folder or to the root), change sharing, or grant team access, with one exception: the owner of the folder the file is in can also move it down into a sub-folder of that folder, when they own that sub-folder and every folder in between. " +
             "team_ids replaces the current set when supplied. " +
             "Returns the file row: owner, is_owner, my_role, sharing, shared_with_teams[] (each { team_id, team_name, role, granted_at }), linked_records_count, size_bytes, content_type, created_at, updated_at.",
         inputSchema: {
             file_id: z.string().uuid().describe("File UUID, the file being changed"),
             name: z.string().optional().describe("New name"),
-            folder_id: z.string().uuid().optional().describe("New parent folder UUID, the folder the file is moved INTO (on lighthouse_documents_update_folder the same name means the folder being changed). The file's owner moves it into any folder they can edit; the owner of the folder it is in can also move it, but only into a folder they own; anyone else gets 403 forbidden. Naming the folder the file is already in also counts as a move, so to rename a file send only name."),
+            folder_id: z.string().uuid().optional().describe("New parent folder UUID, the folder the file is moved INTO (on lighthouse_documents_update_folder the same name means the folder being changed). The file's owner moves it into any folder they can edit; the owner of the folder it is in can also move it, but only down into a sub-folder of that folder that they own, with every folder in between theirs too; anyone else gets 403 forbidden. Naming the folder the file is already in also counts as a move, so to rename a file send only name."),
             clear_folder: z.boolean().optional().describe("Move to workspace root (owner-only)"),
             sharing: z.enum(["private", "workspace"]).optional().describe("Explicit override (null clears to inherit). The same word every other sharing tool takes, and the one a file answers."),
             sharing_status: z.enum(["PRIVATE", "WORKSPACE"]).optional().describe("Legacy name for sharing. Kept forever; sharing wins when both are sent."),
@@ -1716,6 +1784,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_documents_delete_file", {
         title: "Delete File",
+        annotations: DESTRUCTIVE,
         description: "Owner or editor (file-level editor OR editor-on-parent-folder) can delete, provided they also have the files.delete workspace permission. Permanently deletes the file and purges the underlying object from storage. Irreversible.",
         inputSchema: {
             file_id: z.string().uuid().describe("File UUID"),
@@ -1731,6 +1800,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_documents_link_file_to_record", {
         title: "Link File to Record",
+        annotations: ADDS_IF_MISSING,
         description: "Make a file appear on a CRM record's Files tab. Answers THE FILE itself, the same row lighthouse_documents_get_file returns, with its links as they are after the call.",
         inputSchema: {
             file_id: z.string().uuid().describe("File UUID"),
@@ -1749,6 +1819,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_documents_unlink_file_from_record", {
         title: "Unlink File from Record",
+        annotations: DESTRUCTIVE,
         description: "Remove a file→record link. Answers THE FILE itself, the same row lighthouse_documents_get_file returns, with its links as they are after the call.",
         inputSchema: {
             file_id: z.string().uuid().describe("File UUID"),
@@ -1767,6 +1838,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_documents_list_for_record", {
         title: "List a Record's Documents",
+        annotations: READ_ONLY,
         description: "List folders and files linked to a CRM record. Returns { folders, files }. `files` are files linked DIRECTLY to the record; files that live inside a linked folder are NOT flattened into `files`. To read a linked folder's contents, list that folder by its id with lighthouse_documents_list. " +
             "Each row includes my_role ('owner' | 'editor' | 'viewer'), is_owner, owner (the member who owns it: { id, first_name, last_name, full_name, avatar_url, email }), sharing ('private' or 'workspace'), linked_records_count, linked_at, and shared_with_teams[] (each entry has { team_id, team_name, role, granted_at }). " +
             "Cursor-based pagination via meta.folders_next_cursor / meta.files_next_cursor; pass them back as folders_cursor / files_cursor to fetch the next page.",
@@ -1796,6 +1868,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_list_views", {
         title: "List CRM Views",
+        annotations: READ_ONLY,
         description: "Get all saved CRM views, or list views scoped to a specific list. " +
             "Supports built-in types and custom objects. " +
             "Views store filter/sort configurations that can be loaded in search_records. " +
@@ -1815,6 +1888,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_update_view", {
         title: "Update CRM View",
+        annotations: DESTRUCTIVE,
         description: "Update a saved CRM view or list view's name, filters, sort, or layout. " +
             "Automatically detects whether it's a CRM view or list view. " +
             "To change sharing settings, use lighthouse_crm_update_view_sharing instead. " +
@@ -1852,6 +1926,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_get_view", {
         title: "Get CRM View",
+        annotations: READ_ONLY,
         description: "Get a single saved CRM view or list view by ID. Automatically detects the view type. The filters come back as saved, a semantic_search condition with its vector included: reuse such a condition verbatim in lighthouse_crm_search_records or lighthouse_crm_list_list_records. Conditions on lists you cannot open are left out, and so are conditions on custom fields that belong to such a list. The row carries record_type, owner and is_owner (true when the API key's user owns the view). A kanban view's board settings come with it: hidden_kanban_groups (the values whose column is collapsed, always an array) and kanban_summary (the number at the top of each column, or null), both writable through lighthouse_crm_update_view exactly as they are read.",
         inputSchema: {
             id: z.string().uuid().describe("View ID"),
@@ -1867,6 +1942,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_delete_view", {
         title: "Delete CRM View",
+        annotations: DESTRUCTIVE,
         description: "Permanently delete a saved CRM view or list view. Automatically detects the view type.",
         inputSchema: {
             id: z.string().uuid().describe("View ID"),
@@ -1882,6 +1958,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_workspace_me", {
         title: "Get Current User",
+        annotations: READ_ONLY,
         description: "Get the profile of the user this key acts as: id, name, email, avatar, phone_number, status, created_at, workspace_role, permissions and `teams` ([{ id, name, role, joined_at }], [] when they are on none). " +
             "It is the same object lighthouse_workspace_get_user answers for anyone else, so read it once to learn who you are acting as and what that role may do, rather than calling the user tool on yourself.",
         inputSchema: {},
@@ -1896,6 +1973,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_workspace_list_users", {
         title: "List Workspace Users",
+        annotations: READ_ONLY,
         description: "List users in the workspace. Use this to find user IDs for task assignment, note tagging, or filtering by user. " +
             "Supports search by name/email.",
         inputSchema: {
@@ -1916,6 +1994,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_workspace_get_user", {
         title: "Get Workspace User",
+        annotations: READ_ONLY,
         description: "Get a specific workspace user's profile by ID.",
         inputSchema: {
             id: z.string().uuid().describe("User ID"),
@@ -1931,6 +2010,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_workspace_list_teams", {
         title: "List Workspace Teams",
+        annotations: READ_ONLY,
         description: "List all teams in the workspace.",
         inputSchema: {
             limit: z.number().min(1).max(100).default(25),
@@ -1947,6 +2027,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_workspace_get_team", {
         title: "Get Workspace Team",
+        annotations: READ_ONLY,
         description: "Get a specific team by ID with its members.",
         inputSchema: {
             id: z.string().uuid().describe("Team ID"),
@@ -1966,6 +2047,7 @@ export function createServer(apiKey, options = {}) {
     const WEBHOOK_SUBSCRIPTION_WRITES = "This tool only reads: creating and deleting webhook subscriptions is done with the REST API (POST /v1/webhook-subscriptions and DELETE /v1/webhook-subscriptions/{id}) or the SDKs, with an API key, and a subscription can also be created or deleted in the app, under Settings > Developer > Webhooks. A turned-off subscription is not turned back on: delete it and create a new one.";
     server.registerTool("lighthouse_workspace_list_webhook_subscriptions", {
         title: "List Webhook Subscriptions",
+        annotations: READ_ONLY,
         description: "List the webhook subscriptions of the user this key acts as (only their own), newest first, active and turned off alike: each one sends a signed POST to its url whenever a record of its record_type is created or updated. " +
             WEBHOOK_SUBSCRIPTION_SHAPE + " " +
             "WHEN TO USE: \"which webhooks do I have\", \"where are our company updates being sent\", \"why did our integration stop receiving changes\" (read status, disabled_reason and last_delivery). " +
@@ -1985,6 +2067,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_workspace_get_webhook_subscription", {
         title: "Get Webhook Subscription",
+        annotations: READ_ONLY,
         description: "Get one of the webhook subscriptions of the user this key acts as, by id. " +
             WEBHOOK_SUBSCRIPTION_SHAPE + " " +
             "WHEN TO USE: \"is that webhook still on\", \"when did it last deliver\", for one subscription whose id you already have (from lighthouse_workspace_list_webhook_subscriptions). " +
@@ -2003,6 +2086,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_list_attributes", {
         title: "List Discovery Data Fields",
+        annotations: READ_ONLY,
         description: "Get a lightweight catalog of the DATA FIELDS discovery results carry for companies or people: each field's permalink, label, data_type, links_to, read_only, and has_options. " +
             "These are OUTPUT/data fields, NOT filter keys. To FILTER a search you MUST use the prefixed company_* / person_* keys listed in the `filters` parameter of the discovery search tools. " +
             "To keep the response small it does NOT include option values: when a field has has_options=true and you need its allowed values, call lighthouse_discovery_list_options with that permalink (or the dedicated lighthouse_discovery_list_industries / lighthouse_discovery_list_locations / lighthouse_discovery_list_funding_types / lighthouse_discovery_list_tags tools). " +
@@ -2029,6 +2113,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_list_options", {
         title: "List Discovery Field Options",
+        annotations: READ_ONLY,
         description: "Get the allowed values (value, label, color) for a single discovery select / multi_select field. " +
             "Call this when lighthouse_discovery_list_attributes shows has_options=true for a field and you need its valid values. " +
             "Results are paginated (max 100 per page): use `search` to narrow by label, and `limit` / `offset` to page through a field with many values (e.g. locations). " +
@@ -2052,6 +2137,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_search_companies", {
         title: "Search Discovery Companies",
+        annotations: READ_ONLY,
         description: "Search Lighthouse's global company database to DISCOVER new companies. " +
             "This searches Lighthouse's enriched database (millions of companies), NOT your CRM. " +
             "WORKFLOW: 1) Build filters using ONLY the company_* filter keys listed in the `filters` parameter below. " +
@@ -2082,6 +2168,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_search_people", {
         title: "Search Discovery People",
+        annotations: READ_ONLY,
         description: "Search Lighthouse's global people database to DISCOVER new people. " +
             "This searches Lighthouse's enriched database, NOT your CRM. " +
             "WORKFLOW: 1) Build filters using ONLY the person_* filter keys listed in the `filters` parameter below. " +
@@ -2112,6 +2199,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_semantic_search_companies", {
         title: "Semantic Search Companies",
+        annotations: READ_ONLY,
         description: "Find companies by MEANING, not exact keywords. Describe the kind of company you are looking for in plain language (what it does, who it serves, its sector, its business model) and Lighthouse returns the most semantically similar companies from its global database (NOT your CRM), ranked by relevance. " +
             "USE THIS when the request is conceptual or hard to express as exact filters, e.g. 'companies like Stripe but for healthcare', 'startups building developer tools for AI agents', 'sustainable packaging for e-commerce'. " +
             "You CAN combine it with structured filters: pass `filters` using the same company_* keys as lighthouse_discovery_search_companies and they apply together (semantic match AND your filters), e.g. semantically-similar companies that are ALSO headquartered in Germany. " +
@@ -2146,6 +2234,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_semantic_search_people", {
         title: "Semantic Search People",
+        annotations: READ_ONLY,
         description: "Find people by MEANING, not exact keywords. Describe the ideal person in plain language (their role, skills, the industry they work in, their background) and Lighthouse returns the most semantically similar people from its global database (NOT your CRM), ranked by relevance. " +
             "USE THIS when the request is conceptual or hard to express as exact filters, e.g. 'technical co-founders who worked on payments infrastructure', 'ex-FAANG ML engineers now in climate tech'. " +
             "You CAN combine it with structured filters: pass `filters` using the same person_* keys as lighthouse_discovery_search_people and they apply together (semantic match AND your filters), e.g. semantically-similar people who are ALSO based in the UK. " +
@@ -2180,6 +2269,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_lookup_by_domain", {
         title: "Lookup Companies by Domain",
+        annotations: READ_ONLY,
         description: "Look up companies in Lighthouse's global database by their website domain(s). " +
             "Returns enriched company profiles for matching domains. Max 1000 domains per request. " +
             "Each returned profile is condensed (the long growth and workforce history and the activity-signal " +
@@ -2203,6 +2293,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_lookup_by_linkedin", {
         title: "Lookup Companies by LinkedIn",
+        annotations: READ_ONLY,
         description: "Look up companies in Lighthouse's global database by LinkedIn URL(s). " +
             "Returns enriched company profiles for matching LinkedIn company pages. Max 1000 URLs per request. " +
             "Each returned profile is condensed (the long growth and workforce history and the activity-signal " +
@@ -2226,6 +2317,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_lookup_people_by_linkedin", {
         title: "Lookup People by LinkedIn",
+        annotations: READ_ONLY,
         description: "Look up people in Lighthouse's global database by LinkedIn profile URL(s). " +
             "Returns enriched person profiles for matching LinkedIn pages. Max 1000 URLs per request. " +
             "Each returned profile is condensed (the activity-signal feed is omitted and the associated-companies " +
@@ -2249,6 +2341,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_list_saved_searches", {
         title: "List Saved Searches",
+        annotations: READ_ONLY,
         description: "List all saved discovery searches in the workspace. " +
             "Returns saved searches you own and workspace-shared searches. " +
             "Each search includes its filters and type (company or person). " +
@@ -2265,6 +2358,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_list_search_results", {
         title: "List Saved Search Results",
+        annotations: READ_ONLY,
         description: "Run a saved discovery search and get its results. " +
             "The search's saved filters are applied automatically. " +
             "Optionally filter by signal creation date range. " +
@@ -2288,6 +2382,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_list_locations", {
         title: "List Location Options",
+        annotations: READ_ONLY,
         description: "Get available location options (countries and regions) for discovery filters. " +
             "ALWAYS call this to get valid country/region values before filtering by location fields " +
             "(company_hq_country, company_hq_region, person_country, person_region, company_investor_country, etc.). " +
@@ -2308,6 +2403,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_list_industries", {
         title: "List Industry & Category Options",
+        annotations: READ_ONLY,
         description: "Get available industry and category options for discovery filters. " +
             "ALWAYS call this to get valid category values before filtering by company_categories, company_sdg_impact, " +
             "person_current_categories, person_past_categories, person_current_sdg_impact, or person_past_sdg_impact, " +
@@ -2329,6 +2425,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_list_tags", {
         title: "List Tag Options",
+        annotations: READ_ONLY,
         description: "Get the tag options for discovery filters. " +
             "ALWAYS call this to get valid tag values before filtering by company_tags or person_tags. " +
             "Returns {company_tags: [{value, name}], person_tags: [{value, name}]}. " +
@@ -2345,6 +2442,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_list_funding_types", {
         title: "List Funding Type Options",
+        annotations: READ_ONLY,
         description: "Get the funding round types available for the funding discovery filters " +
             "(company_last_funding_type, person_company_last_funding_type). " +
             "Returns an array of { value, label, name } ordered by stage. " +
@@ -2363,6 +2461,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_search_investors", {
         title: "Search Investors by Name",
+        annotations: READ_ONLY,
         description: "Search for investors by name to get their UUIDs for use in discovery filters. " +
             "Use the returned 'id' values in company_investor filter conditions (investor_multi_select type). " +
             "Returns [{id, name, avatar_url}]. Pass the id (or [{id, label}] objects) as the filter value. " +
@@ -2381,6 +2480,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_search_organizations", {
         title: "Search Organizations by Name",
+        annotations: READ_ONLY,
         description: "Search for organizations (companies) by name to get their UUIDs for use in discovery filters. " +
             "Use the returned 'id' values in work_experience_multi_select filter conditions " +
             "(company_team_past_companies, person_past_companies). " +
@@ -2401,6 +2501,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_search_schools", {
         title: "Search Schools by Name",
+        annotations: READ_ONLY,
         description: "Search for educational institutions by name to get their UUIDs for use in discovery filters. " +
             "Use the returned 'id' values in education_multi_select filter conditions " +
             "(company_team_education, person_education). " +
@@ -2420,6 +2521,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_search_entities", {
         title: "Search Entities (companies, people, investors, schools)",
+        annotations: READ_ONLY,
         description: "Similarity-ranked, typo-tolerant search across companies, people, investors, and schools. " +
             "Returns lightweight matches (id, record_type, name, avatar_url, is_discoverable, plus a few " +
             "disambiguators like domain/employees/location) ranked by relevance then popularity (e.g. " +
@@ -2456,6 +2558,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_get_company", {
         title: "Get Company Profile by ID",
+        annotations: READ_ONLY,
         description: "Returns the profile for a single company by id: firmographics, funding, categories, tags, links, " +
             "and the first several associated people. " +
             "To stay within response limits, this returns a condensed view: the long growth and workforce " +
@@ -2482,6 +2585,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_get_person", {
         title: "Get Person Profile by ID",
+        annotations: READ_ONLY,
         description: "Returns the profile for a single person by id: bio, links, founder score, person tags, " +
             "the first several associated companies / work history, and education. " +
             "To stay within response limits, this returns a condensed view: the activity-signal feed is omitted, " +
@@ -2506,6 +2610,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_get_company_traction", {
         title: "Get Company Traction History",
+        annotations: READ_ONLY,
         description: "The traction history of one company in the global database, by company id: the two blocks lighthouse_discovery_get_company omits to stay small. " +
             "workforce_data is the month-by-month headcount and open-job-post history behind the traction charts (series of { date, value } points, oldest first where present); growth_metrics is a summary per tracked metric (headcount, job posts, web traffic, social following and similar, where recorded): { last_value, change_1m, change_3m, change_6m, change_1y, change_2y, change_3y, change_5y, date_last_value }. " +
             "WHEN TO USE: \"what was their headcount in March\", \"is this company growing\", \"when did hiring pick up\", \"how has traffic moved this year\": anything about a value over time or a rate of change. The profile tool only carries the current headcount. " +
@@ -2524,6 +2629,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_get_company_signals", {
         title: "Get Company Signals",
+        annotations: READ_ONLY,
         description: "The detected events for one company in the global database, by company id: the activity-signal feed lighthouse_discovery_get_company omits. " +
             "signals is a list of { type, created_at, timeframe, percentage_change }: a funding round, a headcount or traffic jump, a hiring spike and similar, each with when it was detected and, for a change, over which timeframe and by how much. Sort by created_at yourself; the list is not ordered. " +
             "WHEN TO USE: \"what happened at X recently\", \"did they raise\", \"is headcount spiking\", \"any momentum signals\". For the numbers behind a signal read lighthouse_discovery_get_company_traction. " +
@@ -2542,6 +2648,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_get_person_signals", {
         title: "Get Person Signals",
+        annotations: READ_ONLY,
         description: "The detected events for one person in the global database, by person id: the signal feed lighthouse_discovery_get_person omits. " +
             "signals is a list of { type, created_at, new_company, domain, org_id, predicted_areas }: a new company founded or registered, a stealth period, a departure and similar; org_id is a company id you can pass to lighthouse_discovery_get_company, domain its website. Sort by created_at yourself. " +
             "predicted_areas is what Lighthouse predicts the founder is building, on a stealth or out_of_stealth signal: [{ permalink, label, origin }], permalink being a value of lighthouse_discovery_list_industries → stealth_predicted_areas and origin what the prediction was read from; it is [] on every other signal and when nothing was predicted. " +
@@ -2561,6 +2668,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_discovery_get_entity_by_name", {
         title: "Get Entity Profile by Name",
+        annotations: READ_ONLY,
         description: "DEFAULT way to get the COMPLETE profile of ONE company or person when you have its name. " +
             "Resolves the single best-ranked match and returns its full profile in one call (equivalent to " +
             "lighthouse_discovery_search_entities followed by lighthouse_discovery_get_company / get_person, combined). " +
@@ -2607,6 +2715,7 @@ export function createServer(apiKey, options = {}) {
         "ALWAYS call lighthouse_crm_list_attributes first to discover valid field keys for dimension, measure, and stage_field.";
     server.registerTool("lighthouse_reports_list_dashboards", {
         title: "List Dashboards",
+        annotations: READ_ONLY,
         description: "List all report dashboards accessible to the current user. " +
             "Returns dashboards you own, workspace-shared dashboards, and team-shared dashboards. " +
             "Each dashboard includes: id, name, description, sharing (private/workspace), is_owner, " +
@@ -2623,6 +2732,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_reports_create_dashboard", {
         title: "Create Dashboard",
+        annotations: CREATES,
         description: "Create a new report dashboard. Dashboards contain report widgets (charts, tables, KPIs). " +
             "Requires reports.create permission. Returns the full dashboard object (same format as get dashboard).",
         inputSchema: {
@@ -2648,6 +2758,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_reports_get_dashboard", {
         title: "Get Dashboard",
+        annotations: READ_ONLY,
         description: "Get a single dashboard by ID with all its widgets. " +
             "Returns: id, name, description, sharing, is_owner, owner {id, first_name, last_name, full_name, avatar_url, email}, " +
             "widget_count, shared_with_teams, widgets [{id, name, widget_type, config, created_at, updated_at}], created_at, updated_at.",
@@ -2665,6 +2776,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_reports_update_dashboard", {
         title: "Update Dashboard",
+        annotations: DESTRUCTIVE,
         description: "Update a dashboard's name, description, or sharing. Only the dashboard owner can update. " +
             "Returns the full dashboard object (same format as get dashboard), plus shared_along and audience_cannot_open. " +
             SHARE_ALONG_RULE,
@@ -2690,6 +2802,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_reports_delete_dashboard", {
         title: "Delete Dashboard",
+        annotations: DESTRUCTIVE,
         description: "Permanently delete a dashboard and all its widgets. Only the dashboard owner can delete.",
         inputSchema: {
             id: z.string().uuid().describe("Dashboard ID"),
@@ -2705,6 +2818,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_reports_list_widgets", {
         title: "List Dashboard Widgets",
+        annotations: READ_ONLY,
         description: "Get all widgets for a dashboard. " +
             "Each widget includes: id, name, widget_type, config, created_at, updated_at.",
         inputSchema: {
@@ -2722,6 +2836,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_reports_create_widget", {
         title: "Create Report Widget",
+        annotations: CREATES,
         description: "Create a report widget (chart/table/KPI) on a dashboard. " +
             "WORKFLOW: 1) Call lighthouse_crm_list_attributes to discover field keys for the entity type, " +
             "2) Build a config object using those keys, 3) Create the widget. " +
@@ -2750,6 +2865,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_reports_update_widget", {
         title: "Rename Report Widget",
+        annotations: DESTRUCTIVE,
         description: "Rename a report widget. Only the name can be changed, a widget's type and " +
             "configuration are fixed once created. To change what a widget reports, delete " +
             "it and create a new one. " +
@@ -2771,6 +2887,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_reports_delete_widget", {
         title: "Delete Report Widget",
+        annotations: DESTRUCTIVE,
         description: "Permanently delete a report widget from a dashboard.",
         inputSchema: {
             dashboard_id: z.string().uuid().describe("Dashboard ID"),
@@ -2787,6 +2904,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_reports_get_widget_data", {
         title: "Get Widget Report Data",
+        annotations: READ_ONLY,
         description: "Fetch the aggregated report data for a specific widget. " +
             "Returns the computed data based on the widget's config (dimensions, measures, segments, filters). " +
             "For standard reports: array of {label, label_is_empty, value, segment?, segment_is_empty?} rows (label = the grouped dimension value, value = the aggregated measure, segment = present only when segment_by is set). " +
@@ -2808,6 +2926,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_reports_share_dashboard_with_teams", {
         title: "Share Dashboard with Teams",
+        annotations: ADDS_IF_MISSING,
         description: "Grant team-level access to a dashboard. Only the dashboard owner can share. " +
             "Use lighthouse_workspace_list_teams to find team IDs first. " +
             "Requires reports.edit permission. " +
@@ -2832,6 +2951,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_reports_revoke_dashboard_from_teams", {
         title: "Revoke Dashboard Team Access",
+        annotations: DESTRUCTIVE,
         description: "Revoke team-level access from a dashboard. Only the dashboard owner can revoke. " +
             "Requires reports.edit permission.",
         inputSchema: {
@@ -2850,6 +2970,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_share_view_with_teams", {
         title: "Share View with Teams",
+        annotations: ADDS_IF_MISSING,
         description: "Grant team-level access to a CRM view or list view. Only the view owner can share. " +
             "Use lighthouse_workspace_list_teams to find team IDs first. " +
             "Requires views.share permission. " +
@@ -2875,6 +2996,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_revoke_view_from_teams", {
         title: "Revoke View Team Access",
+        annotations: DESTRUCTIVE,
         description: "Revoke team-level access from a CRM view or list view. Only the view owner can revoke. " +
             "Requires views.share permission. " +
             "Returns formatted view: {id, name, record_type, list_id, view_type, filters, sort, grouped_by, sharing, owner, is_owner, shared_with_teams, created_at}, where is_owner says whether the API key's user owns the view.",
@@ -2894,6 +3016,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_crm_update_view_sharing", {
         title: "Update View Sharing Status",
+        annotations: DESTRUCTIVE,
         description: "Change a CRM view or list view's sharing visibility. Setting to 'private' also removes all team permissions. " +
             "Automatically detects view type. Only the view owner can change sharing. Requires views.share permission. " +
             "Returns formatted view: {id, name, record_type, list_id, view_type, filters, sort, grouped_by, sharing, owner, is_owner, shared_with_teams, created_at, shared_along, audience_cannot_open}, where is_owner says whether the API key's user owns the view. " +
@@ -2918,6 +3041,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_inbox_email_accounts", {
         title: "List Email Accounts",
+        annotations: READ_ONLY,
         description: "List the email accounts the user can access: their own connected mailbox plus mailboxes other workspace " +
             "members shared with them. One account object on all three channels: { id, name (the owner's display name), " +
             "email (the mailbox address), is_owner (true when the account belongs to the API key's user, false for a colleague's), " +
@@ -2943,6 +3067,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_inbox_linkedin_accounts", {
         title: "List LinkedIn Accounts",
+        annotations: READ_ONLY,
         description: "List the LinkedIn messaging accounts the user can access: their own connected account plus accounts other " +
             "workspace members shared with them. The same account object the email and calendar channels return: " +
             "{ id, name (the owner's display name), email (always null on LinkedIn), is_owner (true when the account belongs " +
@@ -2967,6 +3092,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_inbox_email_threads", {
         title: "List Email Threads",
+        annotations: READ_ONLY,
         description: "List email threads (conversations) across every email account the user can read, newest activity first. Filters are " +
             "all optional and combinable: record_id + record_type ('company' or 'person' ONLY) for correspondence with " +
             "a CRM record (person = their email addresses, company = its domains); emails / domains (comma separated lists); " +
@@ -3007,6 +3133,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_inbox_email_thread", {
         title: "Get Email Thread",
+        annotations: READ_ONLY,
         description: "Read one email thread: data.thread (the list's row) plus data.messages, newest first by default. Each message: " +
             "{ id, thread_id, date, direction (sent | received), from { name, email }, to / cc / bcc / reply_to [{ name, email }], " +
             "subject, snippet, text (the plain words of THIS message, with the quoted history of a reply removed and a forwarded block kept), " +
@@ -3046,6 +3173,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_inbox_email_attachment", {
         title: "Read Email Attachment",
+        annotations: READ_ONLY,
         description: "What one email attachment SAYS, as text: PDFs, Word, Excel and PowerPoint files (and their OpenDocument versions), text, CSV and HTML. " +
             "WHEN TO USE: the user asks what an attached file contains (\"summarise the report Jane sent\", \"what are the numbers in the attached model\", \"check the attachment on that email\"). " +
             "Find the message first: lighthouse_inbox_email_threads (a subject, a sender, a date), then lighthouse_inbox_email_thread, whose messages carry attachments [{ id, message_id, filename, ... }] and account { id }. Pass that attachment's id as attachment_id, its message_id, and the message's account.id as account_id. " +
@@ -3078,6 +3206,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_inbox_email_create_draft", {
         title: "Create Email Draft",
+        annotations: CREATES,
         description: "Save an email draft in one of the user's mailboxes. The draft is NOT sent: it lands in the mailbox for the " +
             "user to review, edit and send themselves, and there is no tool that can send it. Use this to prepare a reply " +
             "or a new email on the user's behalf. account_id is REQUIRED (from lighthouse_inbox_email_accounts) and must " +
@@ -3113,6 +3242,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_inbox_linkedin_chats", {
         title: "List LinkedIn Chats",
+        annotations: READ_ONLY,
         description: "List LinkedIn conversations across every LinkedIn account the user can view, newest activity first, " +
             "paginated. Filters are all optional and combinable: record_id + record_type ('company' or 'person' ONLY, where a " +
             "company matches its team members and company page), person_linkedin / company_linkedin (LinkedIn URL or " +
@@ -3154,6 +3284,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_inbox_linkedin_chat_messages", {
         title: "Get LinkedIn Chat Messages",
+        annotations: READ_ONLY,
         description: "Read one LinkedIn conversation: returns the chat object (the same object lighthouse_inbox_linkedin_chats " +
             "returns) plus its messages, paginated, newest first by default (order 'asc' for oldest first), both sides " +
             "or one (direction 'sent' = what the account sent, 'received' = what the other people sent), with optional " +
@@ -3196,6 +3327,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_inbox_calendar_accounts", {
         title: "List Calendar Accounts",
+        annotations: READ_ONLY,
         description: "Calendars the API key's user can read: their own connected calendar (is_owner true) and colleagues' calendars shared with them. " +
             "The same account object the email and LinkedIn channels return: { id, name, email, is_owner, provider (google | microsoft | other), " +
             "status (connected | pending | disconnected), status_reason (credentials | error | stopped | other; null unless disconnected), " +
@@ -3218,6 +3350,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_inbox_calendar_meetings", {
         title: "List Meetings",
+        annotations: READ_ONLY,
         description: "Calendar meetings across every calendar the API key's user can read (their own, plus colleagues' calendars shared with them), read live from the calendar. PAST meetings newest first by default (the last 6 months; pass months up to 36, or after / before, to move the window), or the SCHEDULED ones soonest first with upcoming=true (90 days ahead by default; an explicit before reaches further). " +
             "Narrow by CRM record (record_id + record_type, company or person: the record's addresses and domains are matched), by emails / domains lists (comma separated), by words in the meeting TITLE (query; never the notes), or by one calendar (account_id from lighthouse_inbox_calendar_accounts). No filter lists the user's whole calendar over the window. " +
             "WHEN TO USE: \"when did we last meet X\", \"what meetings do I have next week\", \"have we talked to anyone at acme.com\", \"which calls with this company were recorded\". To find what was DISCUSSED about a topic, list the meetings and read the notes of the likely ones. " +
@@ -3251,6 +3384,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_inbox_calendar_meeting", {
         title: "Get Recorded Meeting",
+        annotations: READ_ONLY,
         description: "One recorded meeting's metadata by meeting_key (" + MEETING_KEY_SOURCES + "): { meeting_key, ical_uid, title, occurred_at, meeting_url (the video link), recording { has_recording, has_transcript, has_notes, duration_seconds, language, recorded_by } (the same object the meetings list carries; recorded_by is the recorder as a workspace member, or null), notes { id, status, created_at }: the note lighthouse_inbox_calendar_meeting_notes returns, or null when there is none the user may read }. The title and the time are the same here as on the meetings list and inside the notes. " +
             "WHEN TO USE: to check whether a transcript or notes exist before reading them, or to answer how long a call lasted. It never returns the transcript or the notes themselves, and the API never returns the recording itself. Not found when the meeting was not recorded or the API key's user may not read it. A recurring meeting keeps the recording of its most recently recorded occurrence. " + MEETING_ACCESS_RULE,
         inputSchema: {
@@ -3267,6 +3401,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_inbox_calendar_meeting_notes", {
         title: "Get Meeting Notes",
+        annotations: READ_ONLY,
         description: "The meeting notes written from one recorded meeting, by meeting_key (" + MEETING_KEY_SOURCES + "): the note in the same shape as lighthouse_crm_get_note (type 'meeting', with the meeting object and the records it is linked to that you can view), plus content_markdown (what was generated: Meeting Context first, then the sections) and is_edited (true when a member changed the note since, in which case content is the version to trust). " +
             "WHEN TO USE: the user asks what was discussed, decided or agreed in a specific meeting, the next steps from a call, or who attended. Lighter than the transcript: prefer it unless the answer depends on exactly what was said. " +
             "Not found when the meeting has no notes yet (see has_notes on the meeting) or the API key's user may not read them; for a recurring meeting the newest occurrence the user may read is returned. " + MEETING_ACCESS_RULE,
@@ -3284,6 +3419,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_inbox_calendar_meeting_transcript", {
         title: "Get Meeting Transcript",
+        annotations: READ_ONLY,
         description: "The transcript of one recorded meeting by meeting_key (" + MEETING_KEY_SOURCES + "), as text: one \"Speaker: text\" line per utterance, in order. A note's meeting_key opens this transcript when that note's meeting.has_transcript is true. " +
             "WHEN TO USE: only when the answer depends on what was actually SAID (an exact quote, a number, who said what, a nuance the notes would flatten). For what was discussed or decided, lighthouse_inbox_calendar_meeting_notes is enough and far smaller. " +
             `A long meeting comes back in windows of max_chars (default ${TRANSCRIPT_WINDOW_CHARS}): meta.has_more true means the meeting continues past this window, so pass meta.next_offset_chars as offset_chars to read on, and never treat a window with has_more as the end of the meeting. ` +
@@ -3306,6 +3442,7 @@ export function createServer(apiKey, options = {}) {
         return server;
     server.registerTool("lighthouse_private_equity_list_saved_searches", {
         title: "List Private Equity Saved Searches",
+        annotations: READ_ONLY,
         description: "List the Private Equity saved searches the user can see in this workspace (their own, the ones shared with the workspace, and the ones shared with one of their teams), ordered by name. " +
             "Each search carries id, name, sharing (private | workspace), shared_with_teams, is_owner, owner, created_at, updated_at, last_run_at and last_run: the stored run its results come from ({ id, created_at, last_fetched_at, result_count, match_count, created_by }, where result_count is how many companies are stored and match_count how many the search matched in the company database, or null), or null when it never ran. The search's filters are not returned. " +
             "READ ONLY: this reads what the workspace already stored. It never runs a search, never fetches new companies and never spends credits; a Private Equity search is run, and paid for, only in the Lighthouse app. " +
@@ -3326,6 +3463,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_private_equity_list_saved_search_results", {
         title: "List Private Equity Saved Search Results",
+        annotations: READ_ONLY,
         description: "Read one page of the companies a Private Equity saved search's LAST run stored, in the order that run returned them. " +
             "Each row is a stored company: id, name, domain, website_url, linkedin_url, short_description, avatar_url, hq ({ country, country_code, region, city }) and hq_label, industry, category, sector, naics ({ code, label }), business_models, employees and revenue_usd ({ value, estimated }), founded_year, company_type, num_locations, crm_id (the id of this workspace's CRM company for it, or null), lighthouse_company (the matching company in Lighthouse's own data, or null), from_lighthouse (the keys whose value was filled from Lighthouse's own data), fetched_at, profile_updated_at, and match ({ snippets, headline }: why a keyword or product search matched it, or null). " +
             "meta carries total, limit, offset, has_more, has_results and run (the stored run the page is read from). A search that never ran, or whose last run is no longer stored, answers an empty page with meta.has_results false. " +
@@ -3348,6 +3486,7 @@ export function createServer(apiKey, options = {}) {
     });
     server.registerTool("lighthouse_private_equity_get_company", {
         title: "Get Private Equity Company",
+        annotations: READ_ONLY,
         description: "Read one company's stored Private Equity profile by company_id: the id of a row returned by lighthouse_private_equity_list_saved_search_results (a text id, not a UUID, and not a Discovery or CRM id). " +
             "Returns the keys of a results row (without match) plus the full profile: legal_names, commercial_names, long_description, long_description_extracted, locations, classification ({ naics_secondary, nace, sic, isic }), target_markets, core_offerings, technology_focus, certification_focus, supply_chain_focus, business_tags, technologies and technologies_total, contact ({ primary_phone, phone_numbers, primary_email, emails }), socials, website_language, profile_created_at, is_fresh and run_count. " +
             "READ ONLY: the profile as a Private Equity search of this workspace stored it, never refreshed. It never fetches the company again and never spends credits. " +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trylighthouse/mcp-server",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "MCP server for the Lighthouse CRM API",
   "homepage": "https://trylighthouse.vc",
   "type": "module",
@@ -18,7 +18,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "rm -rf build && tsc && chmod 755 build/index.js && node scripts/check-no-comments.mjs",
+    "build": "rm -rf build && tsc && chmod 755 build/index.js && node scripts/check-no-comments.mjs && node scripts/check-tool-annotations.mjs",
     "dev": "tsc --watch",
     "test": "node --test test/*.test.mjs",
     "prepublishOnly": "npm run build"