# Suanyo Data agent guide

This guide is for AI coding agents that help a user understand, configure, and use Suanyo Data.

Suanyo Data provides MCP tools for Chinese public-company filings and financial statements. Use it to connect announcements, annual reports, interim reports, quarterly reports, financial-statement fields, reporting periods, disclosure dates, and source links into an agent workflow.

## Boundary

Suanyo Data provides factual public-disclosure data, structured fields, and source references.

No investment advice. No ratings. No trading signals. No market prices.

## What to set up

Add the MCP server to the user's agent environment:

```json
{
  "mcpServers": {
    "suanyo-data": {
      "command": "npx",
      "args": ["@suanyo/mcp-server"],
      "env": {
        "SUANYO_API_KEY": "sk_..."
      }
    }
  }
}
```

After saving the configuration, reload or restart the agent environment so the tools are discovered.

## Core concepts

- Company: the listed company being queried, usually identified by stock symbol such as `600519`.
- Filing: a disclosure file such as an annual report, interim report, quarterly report, or announcement.
- Reporting period: the period represented by a report or financial field, such as `2025`.
- Disclosure date: the date the filing was published.
- Source: the original filing title and link returned with the data.

## Tools

### `get_company_filings`

Use this to find company disclosure files.

Typical inputs:

```yaml
company: "600519"
filing_type: "annual_report"
period: "2025"
```

Typical result:

```yaml
company: company identity
filing: title, type, reporting period, disclosure date, source URL
```

### `get_financial_statement`

Use this to read financial-statement fields for a company and reporting period.

Typical inputs:

```yaml
company: "600519"
period: "2025"
statement: "income"
fields:
  - revenue
  - net_profit
```

Typical result:

```yaml
company: company identity
filing: source filing information
metrics: field, value, unit, currency, reporting period
```

### `search_announcements`

Use this to search announcement events by company, keyword, announcement type, and date range.

Typical inputs:

```yaml
company: "600519"
query: "dividend"
date_from: "2025-01-01"
date_to: "2026-12-31"
```

Typical result:

```yaml
announcements:
  - title
  - disclosure date
  - announcement type
  - source URL
```

### `get_announcement_detail`

Use this after an announcement search when the user needs the detail behind one result.

Typical inputs:

```yaml
announcement_id: "..."
```

Typical result:

```yaml
announcement: title, disclosure date, text excerpts, structured fields, source URL
```

## Response model

Expect responses to keep source information close to the data:

```json
{
  "company": {
    "name": "Kweichow Moutai",
    "symbol": "600519",
    "market": "SSE"
  },
  "filing": {
    "title": "2025 Annual Report",
    "type": "annual_report",
    "report_period": "2025",
    "disclosed_at": "2026-03-28",
    "source_url": "https://..."
  },
  "data": {},
  "warnings": []
}
```

When answering the user, carry the source title, disclosure date, reporting period, and source URL forward when they are relevant.

## Suggested onboarding flow

1. Confirm that the user has a `SUANYO_API_KEY`.
2. Add the MCP server configuration to the agent environment.
3. Reload the environment and verify that Suanyo Data tools are available.
4. Run `search_announcements` for one familiar company.
5. Run `get_company_filings` for the same company and a reporting period.
6. Run `get_financial_statement` for one statement and two fields.
7. Show the user how the returned source fields connect the answer back to the original filing.

## Common fixes

- Missing tools: reload or restart the agent environment after editing MCP configuration.
- Authentication error: check `SUANYO_API_KEY`.
- Empty results: verify company symbol, market, reporting period, filing type, and date range.
- Period mismatch: use the report period the user means, such as `2025`, and keep disclosure date separate.
- Source needed: use the `filing` or `source_url` fields returned by the tool instead of inventing a citation.
- Follow-up question: reuse the previous company, filing, period, or announcement id when the user clearly refers to the same object.

## Good agent behavior

- Ask for the company symbol when the company identity is ambiguous.
- Keep reporting period and disclosure date separate in explanations.
- Prefer structured tool results to search-engine snippets.
- Preserve source links in summaries, comparisons, and generated reports.
- Use another tool call when the user asks for detail outside the current result.