> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pdfnoodle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools Reference

> Complete reference for all pdf noodle MCP tools

pdf noodle MCP provides 7 tools organized into two categories: **PDF Generation** and **Template Management**. This reference documents each tool's parameters, behavior, and usage examples.

<Tip>
  You don't need to memorize tool names or parameters. Simply describe what you want in natural language, and the AI will select the appropriate tool automatically.
</Tip>

## Tool Summary

| Tool                      | Purpose                  | Key Parameters      |
| ------------------------- | ------------------------ | ------------------- |
| `generate_pdf`            | Create PDF from template | templateId, data    |
| `html_to_pdf`             | Convert HTML to PDF      | html, pdfParams     |
| `check_pdf_status`        | Check async PDF status   | requestId           |
| `list_templates`          | List all templates       | —                   |
| `get_template`            | Get template details     | templateId          |
| `get_template_schema`     | Get template variables   | templateId          |
| `create_template_with_ai` | Create template with AI  | displayName, prompt |

***

## PDF Generation Tools

These tools create PDF documents from templates or raw HTML.

### generate\_pdf

Generate a PDF document using a saved template and dynamic data.

<ParamField body="templateId" type="string" required>
  The unique identifier of the template to use. Get this from `list_templates` or the pdf noodle dashboard.
</ParamField>

<ParamField body="data" type="object" required>
  Object containing the template variables. Must match the schema returned by `get_template_schema`. Example: `{"customerName": "John Doe", "invoiceNumber": "INV-001", "items": [...]}`
</ParamField>

<ParamField body="convertToImage" type="boolean" default="false">
  Return a PNG image instead of PDF. Useful for previews or social media.
</ParamField>

<ParamField body="metadata" type="object">
  PDF metadata object. Example: `{"title": "Invoice", "author": "Company Name", "subject": "Invoice #123", "keywords": "invoice, billing"}`
</ParamField>

<ParamField body="hasCover" type="boolean" default="false">
  Hide header and footer on the first page. Useful for title pages.
</ParamField>

<ParamField body="signedUrlExpiresIn" type="number" default="3600">
  URL expiration time in seconds. Default is 1 hour (3600 seconds).
</ParamField>

<ParamField body="s3_bucket" type="string">
  S3 bucket ID for storing the output file. Requires S3 integration. If provided, `s3_key` must also be specified.
</ParamField>

<ParamField body="s3_key" type="string">
  S3 path/key for the output file (e.g., "invoices/2024/inv-001"). Only used when `s3_bucket` is provided.
</ParamField>

**Example Prompts:**

```text theme={null}
Generate an invoice using template inv-2024 with:
- Customer: John Smith
- Items: Consulting ($500), Development ($1200)
- Invoice number: INV-001
```

```text theme={null}
Create a PDF certificate from my certificate template for
"Maria Garcia" who completed "Advanced Python Course" on January 15, 2025
```

***

### html\_to\_pdf

Convert HTML content directly to a PDF document. This tool provides full control over the document structure and styling.

<Warning>
  For best results with `html_to_pdf`, follow the [PDF Best Practices](/integrations/mcp/best-practices) guidelines. Poorly structured HTML can result in broken layouts and awkward page breaks.
</Warning>

<ParamField body="html" type="string" required>
  Complete HTML content to render as PDF. Should include DOCTYPE, html, head, and body tags with proper CSS for print.
</ParamField>

<ParamField body="pdfParams" type="object">
  PDF formatting options object. Properties:

  * `format` (string): Paper size - "A4", "Letter", "Legal", etc.
  * `margin` (object): Page margins with `top`, `right`, `bottom`, `left` (e.g., `{"top": "40px", "right": "40px", "bottom": "40px", "left": "40px"}`)
  * `printBackground` (boolean): Include CSS backgrounds and colors
  * `landscape` (boolean): Landscape orientation
  * `displayHeaderFooter` (boolean): Show header/footer
  * `headerTemplate` (string): HTML template for page headers
  * `footerTemplate` (string): HTML template for page footers

  Example: `{"format": "A4", "margin": {"top": "40px", "right": "40px", "bottom": "40px", "left": "40px"}, "printBackground": true}`
</ParamField>

<ParamField body="convertToImage" type="boolean" default="false">
  Return a PNG image instead of PDF.
</ParamField>

<ParamField body="metadata" type="object">
  PDF metadata object. Example: `{"title": "Report", "author": "Author Name", "subject": "Subject", "keywords": "keyword1, keyword2"}`
</ParamField>

<ParamField body="hasCover" type="boolean" default="false">
  Hide header/footer on the first page.
</ParamField>

<ParamField body="signedUrlExpiresIn" type="number" default="3600">
  URL expiration time in seconds. Default is 1 hour (3600 seconds).
</ParamField>

<ParamField body="s3_bucket" type="string">
  S3 bucket ID for storage. Requires S3 integration. If provided, `s3_key` must also be specified.
</ParamField>

<ParamField body="s3_key" type="string">
  S3 path/key for the output file (e.g., "reports/2024/report.pdf"). Only used when `s3_bucket` is provided.
</ParamField>

**Recommended PDF Parameters:**

```json theme={null}
{
  "format": "A4",
  "margin": {
    "top": "40px",
    "right": "40px",
    "bottom": "40px",
    "left": "40px"
  },
  "printBackground": true
}
```

**Example Prompts:**

```text theme={null}
Convert this markdown report to a PDF with proper formatting,
A4 size, and page numbers in the footer
```

```text theme={null}
Create a PDF from HTML with a table of our Q4 sales data.
Include a header with our logo and footer with page numbers.
```

**Using the PDF Best Practices Skill:**

For complex documents, instruct the AI to use the pdf-best-practices skill first:

```text theme={null}
Using /pdf-best-practices, generate a professional invoice PDF with:
- Company: TechCorp Inc.
- Client: Jane Smith
- Items: Consulting ($2,000), Development ($5,000)
- Include proper page breaks, table formatting, and print-optimized CSS
```

```text theme={null}
Following the pdf-best-practices guidelines, create a multi-page report PDF
from this data. Make sure tables don't break across pages and headings
stay with their content.
```

<Tip>
  When you reference `/pdf-best-practices` or ask the AI to follow the pdf-best-practices skill, the AI will automatically apply proper CSS rules for page breaks, margins, table formatting, and print-optimized styling.
</Tip>

***

### check\_pdf\_status

Check the status of an asynchronous PDF generation request.

<ParamField body="requestId" type="string" required>
  The request ID returned from a queued PDF generation.
</ParamField>

**Response States:**

| Status    | Meaning                               |
| --------- | ------------------------------------- |
| `SUCCESS` | PDF is ready, download URL provided   |
| `ONGOING` | Still processing, check again shortly |
| `FAILED`  | Generation failed, try again          |

**Example Prompt:**

```text theme={null}
Check the status of PDF request abc123
```

<Note>
  Most PDF generations complete synchronously. This tool is only needed for large or complex documents that are queued for background processing.
</Note>

***

## Template Management Tools

These tools help you work with reusable PDF templates.

### list\_templates

Retrieve all PDF templates in your account.

*This tool has no parameters.*

**Returns:** A list of templates with their display names and IDs.

**Example Prompts:**

```text theme={null}
Show me all my PDF templates
```

```text theme={null}
What templates do I have available?
```

***

### get\_template

Fetch details of a specific template including its status.

<ParamField body="templateId" type="string" required>
  The unique ID of the template to retrieve.
</ParamField>

**Returns:** Template name, ID, and status (COMPLETED, ONGOING, or FAILED).

**Status Values:**

| Status      | Meaning                         |
| ----------- | ------------------------------- |
| `COMPLETED` | Template is ready to use        |
| `ONGOING`   | Template is still being created |
| `FAILED`    | Template creation failed        |

<Note>
  The status field is only relevant when you've created a template using `create_template_with_ai` via MCP or the API. Template creation typically takes 1-2 minutes. Use this tool to check if your new template is ready.
</Note>

**Example Prompts:**

```text theme={null}
Get details for template tmp_abc123
```

```text theme={null}
Check if my new invoice template is ready yet
```

***

### get\_template\_schema

Retrieve the variables and schema required by a template.

<ParamField body="templateId" type="string" required>
  The ID of the template to get the schema for.
</ParamField>

**Returns:** Object describing all template variables and their structure. The schema shows the exact data structure needed for the `data` parameter in `generate_pdf`.

**Example Prompts:**

```text theme={null}
What variables does my invoice template need?
```

```text theme={null}
Show me the schema for template tmp_invoice_v2
```

<Tip>
  Use this tool before `generate_pdf` to understand exactly what data a template expects. The AI will format your data correctly based on the schema.
</Tip>

***

### create\_template\_with\_ai

Create a new reusable PDF template using AI from a natural language description.

<ParamField body="displayName" type="string" required>
  Human-readable name for the template (e.g., "Invoice Template", "Meeting Notes").
</ParamField>

<ParamField body="prompt" type="string" required>
  Detailed description of the template design, layout, and fields. Be specific about:

  * Document type and purpose
  * Sections and their content
  * Data fields that should be variable
  * Styling preferences (colors, fonts)
  * Any images or logos to include
</ParamField>

<ParamField body="fileUrl" type="string">
  Optional URL to a reference PDF or image for design inspiration. The AI will use this as a reference when creating the template.
</ParamField>

**Example Prompts:**

```text theme={null}
Create a professional invoice template with:
- Company logo placeholder at the top
- Invoice number, date, and due date fields
- Bill-to section with customer details
- Line items table with description, quantity, unit price, total
- Subtotal, tax, and grand total section
- Payment terms at the bottom
- Modern design with blue accent colors
```

```text theme={null}
Create a certificate template based on this example: https://example.com/cert.pdf
It should have fields for recipient name, course title, completion date, and instructor signature
```

<Note>
  Template creation typically takes 1-2 minutes. Use `get_template` with the returned ID to check when it's ready.
</Note>

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Natural Language" icon="comments">
    Describe what you want instead of specifying exact parameters. The AI handles the technical details.
  </Card>

  <Card title="Check Schemas First" icon="list-check">
    Use `get_template_schema` before generating PDFs to ensure you provide all required data.
  </Card>

  <Card title="Follow PDF Guidelines" icon="file-pdf">
    For `html_to_pdf`, review the [Best Practices](/integrations/mcp/best-practices) to avoid formatting issues.
  </Card>

  <Card title="Be Specific" icon="bullseye">
    More detail in your prompts leads to better results, especially for template creation.
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Examples" icon="lightbulb" href="/integrations/mcp/examples">
    See these tools in action with real prompts
  </Card>

  <Card title="Best Practices" icon="star" href="/integrations/mcp/best-practices">
    Learn HTML-to-PDF formatting guidelines
  </Card>
</CardGroup>