# Loanie Agent Skills

> Agent-readable guidance for mortgage discovery, property lookup, calculators, referral checks, and loan-application handoff.

## Preferred discovery endpoints

- MCP manifest: `https://loanie.co.nz/.well-known/mcp.json`
- OpenAI function calling: `https://loanie.co.nz/.well-known/openai-function-calling.json`
- LLM overview: `https://loanie.co.nz/llms.txt`
- Full docs: `https://loanie.co.nz/llms-full.txt`
- AI-ready page: `https://loanie.co.nz/en/ai-ready`

## Global execution rules

- Prefer read-only tools for research, comparison, and calculations.
- Confirm explicit user intent before calling `submit_loan_application`.
- Never ask for or transmit internet banking credentials, card CVV values, or government ID numbers.
- When using MCP, parse `content[0].text` as JSON before reading tool outputs.
- When using OpenAI function calling, fetch the published `tools` array and pass it directly to `client.responses.create({ tools })`.

## Skills

### Compare NZ mortgage rates

Use when the user wants current mortgage rates, a ranking of lenders, or a comparison of special/fixed terms.

- Primary tool: `get_mortgage_rates`
- Common follow-up: `calculate_repayment`
- Good prompts:
  - Compare current 1-year special rates from the major NZ banks.
  - Rank the lowest 2-year fixed rates available right now.

### Search a property and fetch details

Use when the user has an NZ address or wants property valuation context.

- Primary tools: `search_addresses`, `get_property_details`
- Flow:
  1. Search by free-text address.
  2. Resolve the best `propertyId`.
  3. Fetch full property details.

### Calculate repayments

Use when the user already knows the loan amount, interest rate, and term.

- Primary tool: `calculate_repayment`
- Returns: monthly, fortnightly, weekly repayment, total interest, total cost

### Estimate borrowing capacity

Use when the user wants a high-level affordability estimate before applying.

- Primary tool: `calculate_borrowing_capacity`
- Inputs: income, other income, expenses, dependants, existing loans, deposit, term
- Returns: max borrowing, max property value, repayment estimate, LVR, stress-test rate

### Estimate break fees

Use when the user wants to understand the cost of leaving a fixed mortgage early.

- Primary tool: `estimate_break_fee`
- Important inputs: bank, outstanding balance, current fixed rate, original term, payment amount, fixed-term start date

### Check invitation or referral codes

Use when the user has a Loanie invitation code and wants to know who sent it or what property/expert is attached.

- Primary tool: `get_invitation_info`

### Submit a loan application

Use only when the user clearly wants to create a real Loanie application.

- Primary tool: `submit_loan_application`
- Required confirmation: yes
- Minimum required details: `loanType`, `fullName`, `email`
- Optional details: `phone`, `propertyAddress`, `propertyValue`, `downPayment`, `referralCode`

## OpenAI function-calling usage

Fetch `https://loanie.co.nz/.well-known/openai-function-calling.json` and pass the `tools` array into the OpenAI Responses API.

```ts
import OpenAI from "openai";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const { tools } = await fetch(
  "https://loanie.co.nz/.well-known/openai-function-calling.json",
).then((res) => res.json());

const response = await openai.responses.create({
  model: "gpt-5.4",
  input: "Compare current 1-year special mortgage rates from ANZ, ASB, BNZ, Westpac, and Kiwibank.",
  tools,
  tool_choice: "auto",
  parallel_tool_calls: false,
});
```

Notes:

- The published schemas use `strict: true`.
- Optional inputs are represented as nullable fields so the schemas remain strict-mode compatible.
- Treat `submit_loan_application` as a side-effecting action and confirm intent first.

## MCP usage

If the client supports MCP, prefer the public manifest:

```json
{
  "mcpServers": {
    "loanie": {
      "url": "https://loanie.co.nz/api/mcp",
      "transport": "streamable-http"
    }
  }
}
```

## Supported workflows summary

- Mortgage-rate comparison
- Property search and valuation lookup
- Repayment modelling
- Borrowing-capacity estimation
- Break-fee estimation
- Referral / invitation lookup
- Loan application submission