/** Canonical side effects for one caller-visible tool. */ export interface ToolEffects { readonly mutatesTarget: boolean; readonly mutatesSession: boolean; readonly writesFilesystem: boolean; readonly launchesProcess: boolean; readonly accessesNetwork: boolean; readonly changesUiState: boolean; readonly mayDiscardData: boolean; readonly idempotent: boolean; } /** MCP execution hints derived only from canonical effects. */ export interface DerivedToolAnnotations { readonly readOnlyHint: boolean; readonly destructiveHint: boolean; readonly idempotentHint: boolean; readonly openWorldHint: boolean; } const effects = (overrides: Partial = {}): ToolEffects => ({ mutatesTarget: false, mutatesSession: false, writesFilesystem: false, launchesProcess: false, accessesNetwork: false, changesUiState: false, mayDiscardData: false, idempotent: true, ...overrides, }); const evidence = effects({ mutatesSession: true }); const nativeEvidence = effects({ mutatesSession: true, launchesProcess: true }); const browserEvidence = effects({ mutatesSession: true, accessesNetwork: true, }); const sessionEvidence = effects({ mutatesSession: true }); /** Explicit effect audit for every public tool. */ export const TOOL_EFFECTS: Readonly> = { address_name: evidence, comment: evidence, current_address: evidence, current_procedure: evidence, current_document: evidence, goto_address: effects({ mutatesSession: true, changesUiState: true }), inline_comment: evidence, list_bookmarks: evidence, list_documents: evidence, list_names: evidence, list_procedures: evidence, list_segments: evidence, list_strings: evidence, next_address: evidence, prev_address: evidence, procedure_address: evidence, procedure_assembly: evidence, procedure_callees: evidence, procedure_callers: evidence, procedure_info: evidence, read_function_instructions: evidence, read_bytes: evidence, address_to_file_offset: evidence, procedure_references: evidence, procedure_pseudo_code: evidence, resolve_containing_procedure: evidence, search_procedures: evidence, search_strings: evidence, set_address_name: effects({ mutatesTarget: true, mutatesSession: true }), set_addresses_names: effects({ mutatesTarget: true, mutatesSession: true }), set_bookmark: effects({ mutatesTarget: true, mutatesSession: true }), set_comment: effects({ mutatesTarget: true, mutatesSession: true }), set_current_document: effects({ mutatesSession: true, changesUiState: true }), set_inline_comment: effects({ mutatesTarget: true, mutatesSession: true }), unset_bookmark: effects({ mutatesTarget: true, mutatesSession: true, mayDiscardData: true, }), xrefs: evidence, swift_classes: evidence, get_objc_classes: evidence, get_objc_protocols: evidence, batch_decompile: evidence, get_call_graph: evidence, analyze_swift_types: evidence, find_xrefs_to_name: evidence, binary_overview: evidence, analyze_function: evidence, inspect_native_api: effects({ mutatesSession: true, idempotent: false }), trace_feature: effects({ mutatesSession: true, idempotent: false }), find_code_for_string: effects({ mutatesSession: true, idempotent: false }), trace_call_path: effects({ mutatesSession: true, idempotent: false }), inspect_macho: nativeEvidence, inspect_signature: nativeEvidence, inspect_plist: nativeEvidence, list_architectures: nativeEvidence, demangle_swift: nativeEvidence, inspect_artifact: evidence, extract_artifact: effects({ mutatesSession: true, writesFilesystem: true }), inspect_managed_artifact: evidence, inspect_managed_members: evidence, inspect_managed_native_boundaries: evidence, compare_managed_members: sessionEvidence, verify_managed_native_boundaries: sessionEvidence, import_managed_reconstruction: sessionEvidence, plan_managed_runtime_correlation: sessionEvidence, project_managed_application_graph: sessionEvidence, list_browser_targets: browserEvidence, inspect_web_page: browserEvidence, analyze_web_bundle: browserEvidence, observe_web_session: browserEvidence, discover_webmcp_tools: browserEvidence, compare_web_captures: browserEvidence, capture_web_screenshot: browserEvidence, compare_web_screenshots: browserEvidence, capture_browser_scenario: effects({ mutatesTarget: true, mutatesSession: true, writesFilesystem: true, launchesProcess: true, accessesNetwork: true, changesUiState: true, mayDiscardData: true, idempotent: false, }), list_electron_targets: browserEvidence, inspect_electron_page: browserEvidence, capture_electron_scenario: effects({ mutatesTarget: true, mutatesSession: true, writesFilesystem: true, launchesProcess: true, accessesNetwork: true, changesUiState: true, mayDiscardData: true, idempotent: false, }), list_javascript_runtime_targets: browserEvidence, observe_javascript_runtime: browserEvidence, analyze_javascript_application: evidence, reconcile_javascript_runtime: evidence, trace_application_feature: evidence, trace_javascript_semantics: evidence, compare_application_versions: evidence, compare_source_to_bundle: evidence, compare_javascript_export_shapes: evidence, build_reconstruction_obligation_ledger: evidence, run_replay_machine: effects(), run_controlled_replay: effects({ mutatesSession: true, writesFilesystem: true, launchesProcess: true, }), prepare_node_characterization: effects({ mutatesSession: true, launchesProcess: true, }), execute_node_characterization: effects({ mutatesSession: true, writesFilesystem: true, launchesProcess: true, }), evaluate_reconstruction_coverage: effects(), open_binary: effects({ mutatesSession: true, launchesProcess: true }), close_binary: effects({ mutatesSession: true, writesFilesystem: true, mayDiscardData: true, idempotent: false, }), binary_session: effects(), export_evidence_bundle: effects({ writesFilesystem: true, mayDiscardData: true, }), get_evidence_bundle: effects(), get_navigation_context: effects({ mutatesSession: true }), inspect_address_context: effects({ mutatesSession: true }), import_evidence_bundle: effects({ mutatesSession: true }), capture_process_scenario: effects({ mutatesSession: true, writesFilesystem: true, launchesProcess: true, accessesNetwork: true, idempotent: false, }), compare_process_captures: sessionEvidence, compare_artifacts: sessionEvidence, compare_functions: sessionEvidence, compare_bundles: effects({ mutatesSession: true }), find_changed_behavior: sessionEvidence, build_call_path: sessionEvidence, correlate_static_and_runtime: sessionEvidence, verify_reconstruction: sessionEvidence, list_unknowns: effects(), record_unknown: effects({ mutatesSession: true, idempotent: false }), update_unknown: effects({ mutatesSession: true, idempotent: false }), verify_unknown_resolution: effects(), }; /** Derive MCP annotations without tool-name or tool-family heuristics. */ export const annotationsFromEffects = ( value: ToolEffects, ): DerivedToolAnnotations => ({ readOnlyHint: !( value.mutatesTarget || value.mutatesSession || value.writesFilesystem || value.launchesProcess || value.accessesNetwork || value.changesUiState || value.mayDiscardData ), destructiveHint: value.mayDiscardData, idempotentHint: value.idempotent, openWorldHint: value.launchesProcess || value.accessesNetwork, }); /** Resolve the audited metadata for one public tool. */ export const toolContractMetadata = (name: string) => { const audited = TOOL_EFFECTS[name]; if (audited === undefined) throw new Error(`Missing effect audit for ${name}`); return { title: name .split("_") .map((word) => word[0]?.toUpperCase() + word.slice(1)) .join(" "), effects: audited, annotations: annotationsFromEffects(audited), }; };