{
  "openapi": "3.1.0",
  "info": {
    "title": "FINLY public Agent API",
    "version": "finly-agent-access-1"
  },
  "paths": {
    "/agent/v1/public/tools/calculate_ltv_ratio": {
      "post": {
        "operationId": "calculate_ltv_ratio",
        "summary": "יחס הלוואה לשווי. Divide the explicitly provided numerator by denominator. No regulatory caps, eligibility verdict, fallback rates or customer identifiers.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "loan_agorot": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 10000000000
                  },
                  "property_value_agorot": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10000000000
                  }
                },
                "required": [
                  "loan_agorot",
                  "property_value_agorot"
                ],
                "additionalProperties": false,
                "$schema": "http://json-schema.org/draft-07/schema#"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validated result or explicit no_action",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "http://json-schema.org/draft-07/schema#",
                  "type": "object",
                  "properties": {
                    "request_id": {
                      "type": "string"
                    },
                    "schema_version": {
                      "const": "finly-agent-access-1"
                    },
                    "tool": {
                      "const": "calculate_ltv_ratio"
                    },
                    "response_kind": {
                      "const": "calculation"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "success",
                        "insufficient_data",
                        "needs_review",
                        "stale_data",
                        "consent_required",
                        "approval_required",
                        "pending",
                        "conflict",
                        "unsupported",
                        "temporarily_unavailable",
                        "rate_limited",
                        "not_found_or_not_authorized",
                        "revoked",
                        "expired",
                        "delivery_unknown"
                      ]
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "assumptions": {
                      "type": "array",
                      "items": {}
                    },
                    "limitations": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "next_actions": {
                      "type": "array",
                      "items": {}
                    },
                    "receipt": {
                      "type": "object"
                    },
                    "evidence": {
                      "type": "array",
                      "items": {}
                    },
                    "result": {
                      "type": "object",
                      "properties": {
                        "ltv_ratio": {
                          "type": "number",
                          "minimum": 0
                        },
                        "hypothetical": {
                          "type": "boolean",
                          "const": true
                        }
                      },
                      "required": [
                        "ltv_ratio",
                        "hypothetical"
                      ],
                      "additionalProperties": false,
                      "$schema": "http://json-schema.org/draft-07/schema#"
                    },
                    "no_action": {
                      "$schema": "http://json-schema.org/draft-07/schema#",
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "missing_fields": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "retry_after_ms": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "code"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "request_id",
                    "schema_version",
                    "tool",
                    "response_kind",
                    "status",
                    "as_of",
                    "assumptions",
                    "limitations",
                    "next_actions",
                    "receipt"
                  ],
                  "additionalProperties": false,
                  "oneOf": [
                    {
                      "required": [
                        "result"
                      ],
                      "properties": {
                        "status": {
                          "const": "success"
                        }
                      },
                      "not": {
                        "required": [
                          "no_action"
                        ]
                      }
                    },
                    {
                      "required": [
                        "no_action"
                      ],
                      "properties": {
                        "status": {
                          "not": {
                            "const": "success"
                          }
                        }
                      },
                      "not": {
                        "required": [
                          "result"
                        ]
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Unavailable capability"
          },
          "429": {
            "description": "Retry after the returned interval"
          }
        }
      }
    },
    "/agent/v1/public/tools/calculate_payment": {
      "post": {
        "operationId": "calculate_payment",
        "summary": "Calculate a hypothetical fixed-rate unindexed annuity from explicit inputs. Money is integer agorot; annual interest is a decimal. No bank offer, eligibility or savings recommendation.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "principal_agorot": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10000000000
                  },
                  "nominal_annual_decimal": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 0.5
                  },
                  "term_months": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 360
                  }
                },
                "required": [
                  "principal_agorot",
                  "nominal_annual_decimal",
                  "term_months"
                ],
                "additionalProperties": false,
                "$schema": "http://json-schema.org/draft-07/schema#"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validated result or explicit no_action",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "http://json-schema.org/draft-07/schema#",
                  "type": "object",
                  "properties": {
                    "request_id": {
                      "type": "string"
                    },
                    "schema_version": {
                      "const": "finly-agent-access-1"
                    },
                    "tool": {
                      "const": "calculate_payment"
                    },
                    "response_kind": {
                      "const": "calculation"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "success",
                        "insufficient_data",
                        "needs_review",
                        "stale_data",
                        "consent_required",
                        "approval_required",
                        "pending",
                        "conflict",
                        "unsupported",
                        "temporarily_unavailable",
                        "rate_limited",
                        "not_found_or_not_authorized",
                        "revoked",
                        "expired",
                        "delivery_unknown"
                      ]
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "assumptions": {
                      "type": "array",
                      "items": {}
                    },
                    "limitations": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "next_actions": {
                      "type": "array",
                      "items": {}
                    },
                    "receipt": {
                      "type": "object"
                    },
                    "evidence": {
                      "type": "array",
                      "items": {}
                    },
                    "result": {
                      "type": "object",
                      "properties": {
                        "monthly_agorot": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "total_paid_agorot": {
                          "type": "integer",
                          "exclusiveMinimum": 0
                        },
                        "total_interest_agorot": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "totals_basis": {
                          "type": "string",
                          "const": "unrounded_payment_times_term"
                        },
                        "hypothetical": {
                          "type": "boolean",
                          "const": true
                        }
                      },
                      "required": [
                        "monthly_agorot",
                        "total_paid_agorot",
                        "total_interest_agorot",
                        "totals_basis",
                        "hypothetical"
                      ],
                      "additionalProperties": false,
                      "$schema": "http://json-schema.org/draft-07/schema#"
                    },
                    "no_action": {
                      "$schema": "http://json-schema.org/draft-07/schema#",
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "missing_fields": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "retry_after_ms": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "code"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "request_id",
                    "schema_version",
                    "tool",
                    "response_kind",
                    "status",
                    "as_of",
                    "assumptions",
                    "limitations",
                    "next_actions",
                    "receipt"
                  ],
                  "additionalProperties": false,
                  "oneOf": [
                    {
                      "required": [
                        "result"
                      ],
                      "properties": {
                        "status": {
                          "const": "success"
                        }
                      },
                      "not": {
                        "required": [
                          "no_action"
                        ]
                      }
                    },
                    {
                      "required": [
                        "no_action"
                      ],
                      "properties": {
                        "status": {
                          "not": {
                            "const": "success"
                          }
                        }
                      },
                      "not": {
                        "required": [
                          "result"
                        ]
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Unavailable capability"
          },
          "429": {
            "description": "Retry after the returned interval"
          }
        }
      }
    },
    "/agent/v1/public/tools/calculate_pti_ratio": {
      "post": {
        "operationId": "calculate_pti_ratio",
        "summary": "יחס החזר להכנסה. Divide the explicitly provided numerator by denominator. No regulatory caps, eligibility verdict, fallback rates or customer identifiers.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "monthly_debt_agorot": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 10000000000
                  },
                  "monthly_net_income_agorot": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10000000000
                  }
                },
                "required": [
                  "monthly_debt_agorot",
                  "monthly_net_income_agorot"
                ],
                "additionalProperties": false,
                "$schema": "http://json-schema.org/draft-07/schema#"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validated result or explicit no_action",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "http://json-schema.org/draft-07/schema#",
                  "type": "object",
                  "properties": {
                    "request_id": {
                      "type": "string"
                    },
                    "schema_version": {
                      "const": "finly-agent-access-1"
                    },
                    "tool": {
                      "const": "calculate_pti_ratio"
                    },
                    "response_kind": {
                      "const": "calculation"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "success",
                        "insufficient_data",
                        "needs_review",
                        "stale_data",
                        "consent_required",
                        "approval_required",
                        "pending",
                        "conflict",
                        "unsupported",
                        "temporarily_unavailable",
                        "rate_limited",
                        "not_found_or_not_authorized",
                        "revoked",
                        "expired",
                        "delivery_unknown"
                      ]
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "assumptions": {
                      "type": "array",
                      "items": {}
                    },
                    "limitations": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "next_actions": {
                      "type": "array",
                      "items": {}
                    },
                    "receipt": {
                      "type": "object"
                    },
                    "evidence": {
                      "type": "array",
                      "items": {}
                    },
                    "result": {
                      "type": "object",
                      "properties": {
                        "pti_ratio": {
                          "type": "number",
                          "minimum": 0
                        },
                        "hypothetical": {
                          "type": "boolean",
                          "const": true
                        }
                      },
                      "required": [
                        "pti_ratio",
                        "hypothetical"
                      ],
                      "additionalProperties": false,
                      "$schema": "http://json-schema.org/draft-07/schema#"
                    },
                    "no_action": {
                      "$schema": "http://json-schema.org/draft-07/schema#",
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "missing_fields": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "retry_after_ms": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "code"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "request_id",
                    "schema_version",
                    "tool",
                    "response_kind",
                    "status",
                    "as_of",
                    "assumptions",
                    "limitations",
                    "next_actions",
                    "receipt"
                  ],
                  "additionalProperties": false,
                  "oneOf": [
                    {
                      "required": [
                        "result"
                      ],
                      "properties": {
                        "status": {
                          "const": "success"
                        }
                      },
                      "not": {
                        "required": [
                          "no_action"
                        ]
                      }
                    },
                    {
                      "required": [
                        "no_action"
                      ],
                      "properties": {
                        "status": {
                          "not": {
                            "const": "success"
                          }
                        }
                      },
                      "not": {
                        "required": [
                          "result"
                        ]
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Unavailable capability"
          },
          "429": {
            "description": "Retry after the returned interval"
          }
        }
      }
    },
    "/agent/v1/public/tools/get_capabilities": {
      "post": {
        "operationId": "get_capabilities",
        "summary": "Discover the currently released public tools and a paginated index of approved topics, questions, claims and guides.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "locale": {
                    "type": "string",
                    "const": "he"
                  },
                  "catalog_cursor": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1024
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 50
                  }
                },
                "additionalProperties": false,
                "$schema": "http://json-schema.org/draft-07/schema#"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validated result or explicit no_action",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "http://json-schema.org/draft-07/schema#",
                  "type": "object",
                  "properties": {
                    "request_id": {
                      "type": "string"
                    },
                    "schema_version": {
                      "const": "finly-agent-access-1"
                    },
                    "tool": {
                      "const": "get_capabilities"
                    },
                    "response_kind": {
                      "const": "knowledge"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "success",
                        "insufficient_data",
                        "needs_review",
                        "stale_data",
                        "consent_required",
                        "approval_required",
                        "pending",
                        "conflict",
                        "unsupported",
                        "temporarily_unavailable",
                        "rate_limited",
                        "not_found_or_not_authorized",
                        "revoked",
                        "expired",
                        "delivery_unknown"
                      ]
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "assumptions": {
                      "type": "array",
                      "items": {}
                    },
                    "limitations": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "next_actions": {
                      "type": "array",
                      "items": {}
                    },
                    "receipt": {
                      "type": "object"
                    },
                    "evidence": {
                      "type": "array",
                      "items": {}
                    },
                    "result": {
                      "type": "object",
                      "properties": {
                        "schema_version": {
                          "type": "string",
                          "const": "finly-agent-access-1"
                        },
                        "capabilities": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string"
                              },
                              "title": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              },
                              "inputSchema": {
                                "type": "object",
                                "additionalProperties": {}
                              },
                              "outputSchema": {
                                "type": "object",
                                "additionalProperties": {}
                              },
                              "annotations": {
                                "type": "object",
                                "properties": {
                                  "readOnlyHint": {
                                    "type": "boolean"
                                  },
                                  "destructiveHint": {
                                    "type": "boolean"
                                  },
                                  "idempotentHint": {
                                    "type": "boolean"
                                  },
                                  "openWorldHint": {
                                    "type": "boolean"
                                  }
                                },
                                "required": [
                                  "readOnlyHint",
                                  "destructiveHint",
                                  "idempotentHint",
                                  "openWorldHint"
                                ],
                                "additionalProperties": false
                              }
                            },
                            "required": [
                              "name",
                              "title",
                              "description",
                              "inputSchema",
                              "outputSchema",
                              "annotations"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "knowledge_catalog": {
                          "type": "object",
                          "properties": {
                            "items": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "kind": {
                                    "type": "string",
                                    "enum": [
                                      "topic",
                                      "question",
                                      "claim",
                                      "guide"
                                    ]
                                  },
                                  "id": {
                                    "type": "string"
                                  },
                                  "title": {
                                    "type": "string"
                                  },
                                  "topic": {
                                    "type": "string"
                                  },
                                  "claim_id": {
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "guide_id": {
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "version": {
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  },
                                  "canonical_url": {
                                    "type": [
                                      "string",
                                      "null"
                                    ]
                                  }
                                },
                                "required": [
                                  "kind",
                                  "id",
                                  "title",
                                  "topic",
                                  "claim_id",
                                  "guide_id",
                                  "version",
                                  "canonical_url"
                                ],
                                "additionalProperties": false
                              }
                            },
                            "next_cursor": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "catalog_version": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "items",
                            "next_cursor",
                            "catalog_version"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "required": [
                        "schema_version",
                        "capabilities",
                        "knowledge_catalog"
                      ],
                      "additionalProperties": false,
                      "$schema": "http://json-schema.org/draft-07/schema#"
                    },
                    "no_action": {
                      "$schema": "http://json-schema.org/draft-07/schema#",
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "missing_fields": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "retry_after_ms": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "code"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "request_id",
                    "schema_version",
                    "tool",
                    "response_kind",
                    "status",
                    "as_of",
                    "assumptions",
                    "limitations",
                    "next_actions",
                    "receipt"
                  ],
                  "additionalProperties": false,
                  "oneOf": [
                    {
                      "required": [
                        "result"
                      ],
                      "properties": {
                        "status": {
                          "const": "success"
                        }
                      },
                      "not": {
                        "required": [
                          "no_action"
                        ]
                      }
                    },
                    {
                      "required": [
                        "no_action"
                      ],
                      "properties": {
                        "status": {
                          "not": {
                            "const": "success"
                          }
                        }
                      },
                      "not": {
                        "required": [
                          "result"
                        ]
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Unavailable capability"
          },
          "429": {
            "description": "Retry after the returned interval"
          }
        }
      }
    },
    "/agent/v1/public/tools/get_claim": {
      "post": {
        "operationId": "get_claim",
        "summary": "Read one versioned public claim with its scope, evidence and review dates.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "locale": {
                    "type": "string",
                    "const": "he"
                  },
                  "claim_id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128,
                    "pattern": "^[a-zA-Z0-9_-]+$"
                  },
                  "claim_version": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  }
                },
                "required": [
                  "claim_id"
                ],
                "additionalProperties": false,
                "$schema": "http://json-schema.org/draft-07/schema#"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validated result or explicit no_action",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "http://json-schema.org/draft-07/schema#",
                  "type": "object",
                  "properties": {
                    "request_id": {
                      "type": "string"
                    },
                    "schema_version": {
                      "const": "finly-agent-access-1"
                    },
                    "tool": {
                      "const": "get_claim"
                    },
                    "response_kind": {
                      "const": "knowledge"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "success",
                        "insufficient_data",
                        "needs_review",
                        "stale_data",
                        "consent_required",
                        "approval_required",
                        "pending",
                        "conflict",
                        "unsupported",
                        "temporarily_unavailable",
                        "rate_limited",
                        "not_found_or_not_authorized",
                        "revoked",
                        "expired",
                        "delivery_unknown"
                      ]
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "assumptions": {
                      "type": "array",
                      "items": {}
                    },
                    "limitations": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "next_actions": {
                      "type": "array",
                      "items": {}
                    },
                    "receipt": {
                      "type": "object"
                    },
                    "evidence": {
                      "type": "array",
                      "items": {}
                    },
                    "result": {
                      "type": "object",
                      "properties": {
                        "claim_id": {
                          "type": "string"
                        },
                        "claim_version": {
                          "type": "string"
                        },
                        "title": {
                          "type": "string"
                        },
                        "statement": {
                          "type": "string"
                        },
                        "topic": {
                          "type": "string"
                        },
                        "question_id": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "scope": {
                          "type": "string",
                          "const": "general_information_israel"
                        },
                        "evidence": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "source_url": {
                                "type": "string"
                              },
                              "section": {
                                "type": "string"
                              },
                              "source_version": {
                                "type": "string"
                              },
                              "approved_at": {
                                "type": "string"
                              },
                              "verified_at": {
                                "type": "string"
                              },
                              "review_due_at": {
                                "type": "string"
                              },
                              "approval_basis": {
                                "type": "string",
                                "const": "existing_public_source_metadata"
                              },
                              "reviewer": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "supports": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "required": [
                              "source_url",
                              "section",
                              "source_version",
                              "approved_at",
                              "verified_at",
                              "review_due_at",
                              "approval_basis",
                              "reviewer",
                              "supports"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "limitations": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "claim_id",
                        "claim_version",
                        "title",
                        "statement",
                        "topic",
                        "question_id",
                        "scope",
                        "evidence",
                        "limitations"
                      ],
                      "additionalProperties": false,
                      "$schema": "http://json-schema.org/draft-07/schema#"
                    },
                    "no_action": {
                      "$schema": "http://json-schema.org/draft-07/schema#",
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "missing_fields": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "retry_after_ms": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "code"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "request_id",
                    "schema_version",
                    "tool",
                    "response_kind",
                    "status",
                    "as_of",
                    "assumptions",
                    "limitations",
                    "next_actions",
                    "receipt"
                  ],
                  "additionalProperties": false,
                  "oneOf": [
                    {
                      "required": [
                        "result"
                      ],
                      "properties": {
                        "status": {
                          "const": "success"
                        }
                      },
                      "not": {
                        "required": [
                          "no_action"
                        ]
                      }
                    },
                    {
                      "required": [
                        "no_action"
                      ],
                      "properties": {
                        "status": {
                          "not": {
                            "const": "success"
                          }
                        }
                      },
                      "not": {
                        "required": [
                          "result"
                        ]
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Unavailable capability"
          },
          "429": {
            "description": "Retry after the returned interval"
          }
        }
      }
    },
    "/agent/v1/public/tools/get_guide": {
      "post": {
        "operationId": "get_guide",
        "summary": "Read approved steps and the canonical FINLY guide link. A bank guide is not a recommendation.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "locale": {
                    "type": "string",
                    "const": "he"
                  },
                  "guide_id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128,
                    "pattern": "^[a-zA-Z0-9_-]+$"
                  }
                },
                "required": [
                  "locale",
                  "guide_id"
                ],
                "additionalProperties": false,
                "$schema": "http://json-schema.org/draft-07/schema#"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validated result or explicit no_action",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "http://json-schema.org/draft-07/schema#",
                  "type": "object",
                  "properties": {
                    "request_id": {
                      "type": "string"
                    },
                    "schema_version": {
                      "const": "finly-agent-access-1"
                    },
                    "tool": {
                      "const": "get_guide"
                    },
                    "response_kind": {
                      "const": "knowledge"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "success",
                        "insufficient_data",
                        "needs_review",
                        "stale_data",
                        "consent_required",
                        "approval_required",
                        "pending",
                        "conflict",
                        "unsupported",
                        "temporarily_unavailable",
                        "rate_limited",
                        "not_found_or_not_authorized",
                        "revoked",
                        "expired",
                        "delivery_unknown"
                      ]
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "assumptions": {
                      "type": "array",
                      "items": {}
                    },
                    "limitations": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "next_actions": {
                      "type": "array",
                      "items": {}
                    },
                    "receipt": {
                      "type": "object"
                    },
                    "evidence": {
                      "type": "array",
                      "items": {}
                    },
                    "result": {
                      "type": "object",
                      "properties": {
                        "guide_id": {
                          "type": "string"
                        },
                        "guide_version": {
                          "type": "string"
                        },
                        "title": {
                          "type": "string"
                        },
                        "steps": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "topic": {
                          "type": "string"
                        },
                        "canonical_url": {
                          "type": "string"
                        },
                        "evidence": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "source_url": {
                                "type": "string"
                              },
                              "section": {
                                "type": "string"
                              },
                              "source_version": {
                                "type": "string"
                              },
                              "approved_at": {
                                "type": "string"
                              },
                              "verified_at": {
                                "type": "string"
                              },
                              "review_due_at": {
                                "type": "string"
                              },
                              "approval_basis": {
                                "type": "string",
                                "const": "existing_public_source_metadata"
                              },
                              "reviewer": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "supports": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "required": [
                              "source_url",
                              "section",
                              "source_version",
                              "approved_at",
                              "verified_at",
                              "review_due_at",
                              "approval_basis",
                              "reviewer",
                              "supports"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "limitations": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "guide_id",
                        "guide_version",
                        "title",
                        "steps",
                        "topic",
                        "canonical_url",
                        "evidence",
                        "limitations"
                      ],
                      "additionalProperties": false,
                      "$schema": "http://json-schema.org/draft-07/schema#"
                    },
                    "no_action": {
                      "$schema": "http://json-schema.org/draft-07/schema#",
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "missing_fields": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "retry_after_ms": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "code"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "request_id",
                    "schema_version",
                    "tool",
                    "response_kind",
                    "status",
                    "as_of",
                    "assumptions",
                    "limitations",
                    "next_actions",
                    "receipt"
                  ],
                  "additionalProperties": false,
                  "oneOf": [
                    {
                      "required": [
                        "result"
                      ],
                      "properties": {
                        "status": {
                          "const": "success"
                        }
                      },
                      "not": {
                        "required": [
                          "no_action"
                        ]
                      }
                    },
                    {
                      "required": [
                        "no_action"
                      ],
                      "properties": {
                        "status": {
                          "not": {
                            "const": "success"
                          }
                        }
                      },
                      "not": {
                        "required": [
                          "result"
                        ]
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Unavailable capability"
          },
          "429": {
            "description": "Retry after the returned interval"
          }
        }
      }
    },
    "/agent/v1/public/tools/search_mortgage_knowledge": {
      "post": {
        "operationId": "search_mortgage_knowledge",
        "summary": "Find approved, current public knowledge by a catalog topic or question ID. No free text or personal data.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "locale": {
                    "type": "string",
                    "const": "he"
                  },
                  "topic": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128,
                    "pattern": "^[a-zA-Z0-9_-]+$"
                  },
                  "question_id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128,
                    "pattern": "^[a-zA-Z0-9_-]+$"
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 50
                  },
                  "cursor": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1024
                  }
                },
                "additionalProperties": false,
                "$schema": "http://json-schema.org/draft-07/schema#"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validated result or explicit no_action",
            "content": {
              "application/json": {
                "schema": {
                  "$schema": "http://json-schema.org/draft-07/schema#",
                  "type": "object",
                  "properties": {
                    "request_id": {
                      "type": "string"
                    },
                    "schema_version": {
                      "const": "finly-agent-access-1"
                    },
                    "tool": {
                      "const": "search_mortgage_knowledge"
                    },
                    "response_kind": {
                      "const": "knowledge"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "success",
                        "insufficient_data",
                        "needs_review",
                        "stale_data",
                        "consent_required",
                        "approval_required",
                        "pending",
                        "conflict",
                        "unsupported",
                        "temporarily_unavailable",
                        "rate_limited",
                        "not_found_or_not_authorized",
                        "revoked",
                        "expired",
                        "delivery_unknown"
                      ]
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "assumptions": {
                      "type": "array",
                      "items": {}
                    },
                    "limitations": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "next_actions": {
                      "type": "array",
                      "items": {}
                    },
                    "receipt": {
                      "type": "object"
                    },
                    "evidence": {
                      "type": "array",
                      "items": {}
                    },
                    "result": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "claim_id": {
                                "type": "string"
                              },
                              "claim_version": {
                                "type": "string"
                              },
                              "title": {
                                "type": "string"
                              },
                              "statement": {
                                "type": "string"
                              },
                              "topic": {
                                "type": "string"
                              },
                              "question_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "scope": {
                                "type": "string",
                                "const": "general_information_israel"
                              },
                              "evidence": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "source_url": {
                                      "type": "string"
                                    },
                                    "section": {
                                      "type": "string"
                                    },
                                    "source_version": {
                                      "type": "string"
                                    },
                                    "approved_at": {
                                      "type": "string"
                                    },
                                    "verified_at": {
                                      "type": "string"
                                    },
                                    "review_due_at": {
                                      "type": "string"
                                    },
                                    "approval_basis": {
                                      "type": "string",
                                      "const": "existing_public_source_metadata"
                                    },
                                    "reviewer": {
                                      "type": [
                                        "string",
                                        "null"
                                      ]
                                    },
                                    "supports": {
                                      "type": "array",
                                      "items": {
                                        "type": "string"
                                      }
                                    }
                                  },
                                  "required": [
                                    "source_url",
                                    "section",
                                    "source_version",
                                    "approved_at",
                                    "verified_at",
                                    "review_due_at",
                                    "approval_basis",
                                    "reviewer",
                                    "supports"
                                  ],
                                  "additionalProperties": false
                                }
                              },
                              "limitations": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              }
                            },
                            "required": [
                              "claim_id",
                              "claim_version",
                              "title",
                              "statement",
                              "topic",
                              "question_id",
                              "scope",
                              "evidence",
                              "limitations"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "catalog_version": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "items",
                        "next_cursor",
                        "catalog_version"
                      ],
                      "additionalProperties": false,
                      "$schema": "http://json-schema.org/draft-07/schema#"
                    },
                    "no_action": {
                      "$schema": "http://json-schema.org/draft-07/schema#",
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "missing_fields": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "retry_after_ms": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "code"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "request_id",
                    "schema_version",
                    "tool",
                    "response_kind",
                    "status",
                    "as_of",
                    "assumptions",
                    "limitations",
                    "next_actions",
                    "receipt"
                  ],
                  "additionalProperties": false,
                  "oneOf": [
                    {
                      "required": [
                        "result"
                      ],
                      "properties": {
                        "status": {
                          "const": "success"
                        }
                      },
                      "not": {
                        "required": [
                          "no_action"
                        ]
                      }
                    },
                    {
                      "required": [
                        "no_action"
                      ],
                      "properties": {
                        "status": {
                          "not": {
                            "const": "success"
                          }
                        }
                      },
                      "not": {
                        "required": [
                          "result"
                        ]
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Unavailable capability"
          },
          "429": {
            "description": "Retry after the returned interval"
          }
        }
      }
    }
  }
}