SheetRender 用の MCP サーバー — AI アシスタントに HTML テンプレートとスプレッドシートデータから PDF をレンダリングする機能を提供します。
API キーを sheetrender.com → 設定 → API キー から取得し、MCP クライアント設定に追加してください:
{
"mcpServers": {
"sheetrender": {
"command": "npx",
"args": ["-y", "@sheetrender/mcp"],
"env": { "SHEETRENDER_API_KEY": "sr_live_..." }
}
}
}SHEETRENDER_API_URL も読み取られ、デフォルトは https://sheetrender.com です。セルフホストまたはステージングインスタンスを指す場合にのみ設定してください。
Related MCP server: rendoc
render_pdf提供された HTML から 1 つの PDF をレンダリングします。
Argument | Type | |
| string | 必須 — 完全な HTML ドキュメント。CSS は |
| object | 任意 — キーが Jinja 変数になります。例えば |
| object | 任意 — 後述。 |
保存された PDF のパスとサイズを返します。512 KB 未満の場合は、base64 リソースとしてインラインで添付されるため、添付ファイルを表示するクライアントはドキュメント自体を表示します。
サーバーには 2 つの制限があります。2 MB を超える HTML は拒否されます — 送信した内容と、data を置換した後のドキュメントの両方で測定されるため、長いデータセットを展開するテンプレートは、作成したマークアップが超えていなくても制限を超える可能性があります。また、無料プランでは、レンダリングされたすべての PDF に「Made with SheetRender」フッターが付きます — render_pdf と render_template の両方で同様です。有料プランでは付きません。
list_templates引数なし。保存された各テンプレートの名前、ID、最終更新日を返します。ユーザーが言及したテンプレート名を、他のツールが必要とする ID に変換するために呼び出します。
render_templateアカウントに保存済みのテンプレートから 1 つの PDF をレンダリングします。
Argument | Type | |
| string | 必須 — |
| object | 必須 — 1 行分の値を Jinja 変数として。 |
| object | 任意。省略するとテンプレートに保存されたページ設定が使用されます。指定すると、このレンダリングではそれが上書きされます。 |
render_pdf と同じ戻り値。
create_batch_jobプロジェクトにアップロード済みのデータセットの行ごとに 1 つの PDF をレンダリングするバックグラウンドジョブをキューに入れます。このサーバーはスプレッドシートをアップロードできません。
Argument | Type | |
| string | 必須 — |
| string | 必須 — テンプレートと同じプロジェクト内のデータセット。 |
| string | 任意 — 出力ファイル名のパターン。例: |
| string | 任意 — 行をグループ化する列。異なる値ごとに 1 つの複数ページ PDF を生成します。 |
get_job でポーリングするジョブ ID を返します。filename_template と group_by はそれぞれテンプレートとプロジェクトに永続化されるため、後続の実行のデフォルトも変更されることに注意してください。
サーバーが公開バッチエンドポイントより前のバージョンの場合、ツールは不明瞭に失敗するのではなく、バッチジョブが利用できないことを報告します。
get_jobjob_id を受け取ります。ステータス、完了行数、失敗行数を返し、ジョブが succeeded、partial、failed、cancelled のいずれかに達すると、レンダリングされた各ドキュメントの ID とファイル名を返します。ジョブが queued、retry_queued、running の間はドキュメントリストは空のままです。これらのドキュメント ID が get_document が受け取るものです。
get_documentdocument_id を受け取り、その単一のレンダリング済み PDF をダウンロードします。ID は完了したバッチの get_job から取得します。他に取得方法はありません。render_pdf と同じ戻り値 — パス、サイズ、512 KB 未満のインラインブロブ。
バッチ全体については、Web アプリの結合 PDF と ZIP が、各ドキュメントを順に取得するよりも優れています。
page_settings両方のレンダリングツールで共有され、すべてのフィールドは任意です:
{
"page_size": "a4",
"orientation": "portrait",
"margins": { "top": 15, "right": 15, "bottom": 15, "left": 15 }
}page_size は小文字 — a3、a4、a5、letter、legal、tabloid のいずれかです。マージンは CSS の長さではなく、ミリメートル単位の単なる数値です。
レンダリングされた PDF はシステムの一時ディレクトリに書き込まれます。API からのエラー — 不正なキー、テンプレートの欠落、レート制限 — は、サーバー自身のメッセージを含むツールエラーとして返されます。
公開 API は API キーごとに毎分 120 リクエストを許可します。それを超えると 429 を返し、ツールはレート制限に達したため、しばらくして再試行する必要があると報告します。バッチジョブの作成は別途、より厳しく計測されます。
ホストの node/npm は不要 — scripts/dev.sh install、scripts/dev.sh deno task build。
MIT ライセンス。
SheetRender turns HTML templates plus spreadsheet rows into rendered PDFs. This tool queues a batch job that renders one PDF per row of a dataset, and returns the job id.
Use it when the user wants many documents at once — "an invoice for every row", "one letter per employee" — rather than calling render_template in a loop.
The full sequence, all of it available here:
list_templates — the user's designs, and the template_id for the rest.
create_dataset (rows you hold as JSON) or upload_dataset (a local .csv/.xlsx) — returns the dataset_id. list_datasets finds one that already exists.
create_batch_job — this tool, returning a job id.
get_job — poll until the status is finished; it then lists the document ids.
get_document — download any of those PDFs.
The dataset must belong to the same template's project, which is where create_dataset or upload_dataset put it. Rendering happens in the background, so the job id comes back long before the PDFs do.
filename_template and group_by name columns by their sanitized key, which create_dataset, upload_dataset and list_datasets all report — it is often not the header text verbatim ("Invoice No" becomes invoice_no). Both are saved onto the template/project, so they change the defaults for later runs, not just this one. Only pass them when the user asked to change how output is named or grouped.
| Name | Required | Description | Default |
|---|---|---|---|
| group_by | No | Column name to group rows by, producing one multi-page PDF per distinct value instead of one per row. Saved to the project. | |
| dataset_id | Yes | Dataset id from create_dataset, upload_dataset or list_datasets. It must belong to the same template's project. | |
| template_id | Yes | Template id from list_templates. | |
| filename_template | No | Naming pattern for output files, with column placeholders, e.g. "invoice-{{ invoice_no }}". Saved to the template. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and meets it: it discloses that the dataset must belong to the same template's project, that rendering is asynchronous so the job id returns before the PDFs exist, and — critically for a mutation-style side effect — that filename_template and group_by are 'saved onto the template/project, so they change the defaults for later runs, not just this one.' That persistence warning is exactly the kind of hidden consequence annotations would otherwise supply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose and the sibling contrast are front-loaded, and the numbered workflow is scannable. It is on the long side and the 'SheetRender turns HTML templates plus spreadsheet rows into rendered PDFs' framing sentence is partly scene-setting, but the remaining sentences each carry routing or constraint information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description tells the agent what comes back (a job id), how to get the results (get_job polling, get_document downloads), and what preconditions must hold (dataset in the same project). For a 4-param tool with no annotations, nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description goes beyond it by explaining that column names must be sanitized keys ('Invoice No' becomes invoice_no) reported by create_dataset/upload_dataset/list_datasets, and that these two params persist as project defaults — details found only in prose, not in the schema strings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening states a specific verb and resource: 'queues a batch job that renders one PDF per row of a dataset, and returns the job id.' It explicitly contrasts with the sibling render_template ('rather than calling render_template in a loop'), so an agent can distinguish batch from single-render without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete usage condition ('when the user wants many documents at once — an invoice for every row, one letter per employee'), names the alternative to avoid, and lays out the full 5-step workflow with which sibling produces each required id. It also states when NOT to pass the optional params: 'Only pass them when the user asked to change how output is named or grouped.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
SheetRender turns HTML templates plus spreadsheet rows into rendered PDFs. This tool turns rows you already hold — as JSON — into a dataset a batch job can render, and returns the dataset id plus the column keys.
This is the normal way to start a batch: the user asks for "an invoice for each of these clients" or "a letter per employee", you assemble the rows, and this uploads them. Use upload_dataset instead when the data is already a file on disk, and list_datasets when the user is referring to a dataset that already exists.
rows is a flat array of flat objects, one per document: [{"client": "Acme", "total": 42}, {"client": "Globex", "total": 17}]. The header is the union of every row's keys in first-seen order, so rows need not agree on their keys — a missing one is a blank cell, not a shifted row. Values must be strings, numbers, booleans or null; nested objects and arrays are rejected, so flatten or stringify them first. So are NaN, Infinity and whole numbers past 2^53 (send those as strings to keep them exact).
The dataset is attached to the template's project, which means every template in that project can render it and it stays available to later jobs.
Limits: 50,000 rows and 500,000 cells (rows x columns) per call. The row cap applies to JSON rows only — a bigger sheet can still go through upload_dataset as a file, which is bounded by size and cells rather than rows. Creating a dataset is free; only rendering counts against the account's plan.
Returns the dataset id and, for each column, the sanitized key. That key — not the original header — is what the template's placeholders, filename_template and group_by address, so read it off this result rather than guessing from the header text.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional label for the dataset, used as its stored filename so the user recognises it later, e.g. "march-invoices". | |
| rows | Yes | One flat object per document. Keys become spreadsheet columns; values must be scalars (string, number, boolean or null). | |
| template_id | Yes | Template id from list_templates. The dataset lands in that template's project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and does so richly: it discloses the flat-array/flat-object shape requirement, union-of-keys header semantics with missing keys becoming blanks, scalar-only value rules, rejection of NaN/Infinity/values past 2^53, the 50,000-row and 500,000-cell caps, that creation is free (only rendering is billed), and that the dataset is attached to the template's project and reusable by later jobs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, then constraints, then limits, then return semantics in a logical order. It is on the long side and the opening 'SheetRender turns HTML templates...' line is arguably ambient context, but every paragraph earns its place by resolving a real ambiguity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by stating what is returned (dataset id plus per-column sanitized keys) and warning that the sanitized key is what the template must reference. Combined with the limits, cost model, and placement rules, an agent has everything needed to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the union-of-keys header derivation, the exact-number caveat (send large integers as strings), and that the returned sanitized `key` — not the original header — is what placeholders, filename_template and group_by address. That is meaningful semantics the schema does not carry.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('turns rows ... into a dataset') and immediately distinguishes itself from siblings by naming upload_dataset and list_datasets with the conditions that select them. An agent can tell exactly what this does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use ('the normal way to start a batch', with the user-intent example 'an invoice for each of these clients'), plus explicit when-not with named alternatives: upload_dataset for data already on disk, list_datasets for an existing dataset. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Design a saved template from exactly one of dataset_id, inline rows, or data_base64 with data_filename (CSV or XLSX, up to 10 MB), and an example, brief, or style_id. Use an example alone, or a brief with optional style_id. Examples accept PDF, PNG, JPG, WebP or DOCX as base64 with a filename. Local data_path can supply the data; example_path can supply the example. Waits up to 3 minutes; returns the design status, template id, mapping and preview URL.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Template name. | |
| rows | No | Flat data rows; use exactly one data source. | |
| brief | No | Written design instructions. | |
| style_id | No | Saved style id. | |
| data_path | No | Local CSV or XLSX file path; at most 10 MB; ~ is expanded. | |
| dataset_id | No | Existing dataset id; use exactly one data source. | |
| data_base64 | No | Base64 CSV or XLSX contents; at most 10 MB decoded. | |
| example_path | No | Local example file path; ~ is expanded. | |
| fit_one_page | No | Fit the design onto one page. | |
| data_filename | No | Data filename including .csv or .xlsx extension. | |
| example_base64 | No | Base64 example file contents. | |
| example_filename | No | Example filename including its extension. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations the description carries the full load, and it delivers real behavioral detail: a 3-minute wait, 10 MB size cap, accepted formats (CSV/XLSX for data; PDF/PNG/JPG/WebP/DOCX for examples), and the returned fields (status, template id, mapping, preview URL). It does not mention permission/auth requirements, nor explicitly flag that this persists a new artifact, which is the main gap for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Key constraints (the exclusive-or data source and the example/brief rule) are front-loaded, and every sentence carries a constraint, limit, or return value. It is dense to the point of being run-on in places, but there is little wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter tool with no annotations and no output schema, the description is unusually complete: it covers input combinations, file types, size limits, latency, and enumerates the return values. Remaining gaps are auth/permission expectations and the meaning of the returned 'design status'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: the exclusive-or relationship among data sources and the 'example alone' vs 'brief with optional style_id' rule. data_path/example_path are also framed as local-file alternatives to their base64 counterparts, which the schema treats as independent fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Design a saved template') and immediately scopes exactly what inputs produce that template, so an agent knows this creates a persisted template rather than rendering one. It never names or distinguishes itself from nearby siblings such as render_template or get_design, so sibling differentiation is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit composition rules: data must come from exactly one of dataset_id / inline rows / data_base64+data_filename, and the design source is 'an example alone, or a brief with optional style_id.' That is clear when-to-use guidance for the parameter combinations. It stops short of saying when NOT to use this tool or when to prefer render_template instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a design's status and, when complete, its template id, name, mapping and preview URL.
| Name | Required | Description | Default |
|---|---|---|---|
| design_id | Yes | Design id returned by design_template. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses conditional return behavior — that template id, name, mapping and preview URL only appear once the design is complete — but says nothing about the not-yet-complete case (pending status, errors), auth requirements, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that leads with the primary output (status) and then qualifies the conditional extras. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotations, so the description is the only source of return-shape information. It names the returned fields but does not enumerate possible status values or explain the incomplete-state response, leaving a meaningful gap for a status tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema already states design_id is 'Design id returned by design_template.' The description adds no further meaning about the id's format or provenance, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (Get) and resource (a design), and even enumerates the payload it returns (status, template id, name, mapping, preview URL). It does not distinguish itself from siblings like design_template or get_job, so an agent must infer that design_template is the producer and this is the status poller.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'when complete' implies this is a polling/status-check tool rather than a fetch of a finished artifact, which gives implied usage. However, it never states when to call it versus design_template, render_template, or get_job, and gives no polling cadence or terminal-condition guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
SheetRender turns HTML templates plus spreadsheet rows into rendered PDFs. This tool downloads one PDF produced by a batch job and returns the path to the saved file.
document_id comes from get_job on a finished batch — that is the only place these ids appear, so call get_job first and take an id from its document list. A document id is not a template id or a job id.
Use it to fetch a specific output the user asked about, or to spot-check a batch. Fetching every document of a large batch one at a time is slow; point the user at the SheetRender web app for the merged PDF or ZIP instead.
Returns the temp-file path and size; PDFs under 512 KB are also attached inline.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | Document id from a finished job's document list in get_job. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It discloses that the return includes a temp-file path and size, that PDFs under 512 KB are attached inline, and warns about performance when fetching many documents. It also notes the provenance of document_id. While it doesn't mention error handling or permissions, it covers the essential behavior for a download tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: the first sentence states the core purpose, followed by id provenance, usage guidance, and return behavior. Every sentence adds value with no fluff, and the most critical information (spoiler: the id source) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers all necessary aspects: what it does, how to obtain the id, when to use it vs alternatives, and what the return includes. Nothing essential is missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes document_id with high coverage, but the description adds crucial disambiguation: it explains the id comes specifically from get_job's document list and clarifies it is not a template or job id. This goes beyond the schema's baseline, making parameter meaning clearer for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific verb (download), resource (PDF from a batch job), and distinguishes it from siblings like render_pdf and get_job. It also clarifies that document_id comes from get_job, making the tool's role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use the tool (fetch a specific document or spot-check a batch) and when to instead direct the user to the SheetRender web app for bulk downloads. It also references get_job for obtaining valid IDs, providing clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
SheetRender turns HTML templates plus spreadsheet rows into rendered PDFs. This tool reports the progress of a batch job started by create_batch_job.
Returns the status, rows done/failed, and — once the job reaches a finished state ("succeeded", "partial", "failed" or "cancelled") — the id and filename of every rendered document. The document list is empty while the job is still in "queued", "retry_queued" or "running", so poll again after a short wait rather than assuming zero documents.
Pass those document ids to get_document to download the individual PDFs.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Job id returned by create_batch_job. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With zero annotations, the description carries the full behavioral burden and succeeds. It discloses the asynchronous polling nature, enumerates the complete state machine (queued, retry_queued, running, succeeded, partial, failed, cancelled), explains that the document list is empty during in-progress states, and specifies what becomes available once finished. This is exactly the behavioral context an agent needs to avoid misinterpreting empty results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short paragraphs, zero filler. The purpose and polling caveat are front-loaded; the SheetRender context sentence and the get_document routing both earn their place. The state enumeration is necessary, not redundant, given the target states versus document-list-availability states must be distinguished.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema and no annotations, the description fully compensates: it explains the returned fields (status, rows done/failed, document ids/filenames), the conditional availability of results, and the follow-up action. For a single-parameter polling tool, nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — job_id is documented as 'Job id returned by create_batch_job.' The description reinforces but does not extend this: it references 'the id' of every rendered document but adds no new formatting or validation details beyond the schema. Baseline 3 is appropriate since the schema already carries the semantic weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: 'reports the progress of a batch job started by create_batch_job' — it monitors a job rather than producing content. It distinguishes itself from siblings by explaining the workflow position (reports on create_batch_job output, feeds get_document). The title 'Check a batch PDF job' reinforces the purpose without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description names the prerequisite sibling (create_batch_job), the successor (get_document for downloading), and gives explicit call-timing guidance: poll again while status is in 'queued', 'retry_queued' or 'running' rather than treating an empty document list as zero results. This is concrete, actionable when-to-use guidance that maps the tool into a larger workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
SheetRender turns HTML templates plus spreadsheet rows into rendered PDFs. This tool lists the datasets a batch job can render with a given template — everything in that template's project, newest first — with each one's id, row count and column keys.
Call it when the user refers to data they have already loaded ("use the customer list I uploaded") so you can find its id, or to re-run a batch over an existing dataset instead of creating a duplicate. When there is nothing suitable, create one with create_dataset or upload_dataset.
It is also the quickest way to see a dataset's sanitized column keys before writing a filename_template or choosing group_by.
| Name | Required | Description | Default |
|---|---|---|---|
| template_id | Yes | Template id from list_templates. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden, and it delivers non-obvious behavior: results are project-wide rather than restricted to the template, ordered newest first, and include id, row count and column keys. It stops short of stating pagination/result limits or whether the operation is purely read-only, so the safety and volume profile is still partially inferred.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with what the tool is and what it returns before moving to usage and the column-key tip; every sentence carries information. It runs to three paragraphs where two would suffice, but nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must describe returns itself — it does so explicitly (id, row count, column keys) plus ordering and scope. For a single-parameter list tool, an agent has everything needed to call and interpret it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is one parameter with 100% schema description coverage, so the schema already documents template_id and its provenance (from list_templates). The description adds domain context about what the id scopes but no format or syntax detail beyond the schema, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb and resource ('lists the datasets a batch job can render with a given template') and pins down scope: everything in that template's project, newest first, with id, row count and column keys. That is enough to distinguish it from create_dataset, upload_dataset and list_templates without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit triggering condition ('when the user refers to data they have already loaded') plus a second concrete use case (re-running a batch over an existing dataset instead of duplicating). It also names the alternatives to use when nothing fits — create_dataset or upload_dataset — so routing decisions are fully determined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
SheetRender turns HTML templates plus spreadsheet rows into rendered PDFs. This tool lists the templates saved in the user's account, with the id each one needs.
Call it first whenever the user refers to a template by name ("render the invoice template") so you can map that name to an id — every other tool here takes a template_id, including create_dataset and list_datasets. Takes no arguments.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden; it discloses that the operation is a read ('lists'), is scoped to the user's account, and returns templates together with their ids. It is silent on ordering, result size/pagination, and account/permission requirements, which keeps it short of a 5 for an un-annotated tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Effectively front-loaded: the domain context comes first, then the action, then the routing guidance. The closing 'Takes no arguments' is mildly redundant against the empty schema, and the middle sentence is long, but no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a no-arg, annotation-free, no-output-schema listing tool, the description supplies the essential context: what it returns, why it exists, and when to call it. Some return-value detail (ordering, size limits) is absent, which is the only real gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the schema baseline is 4; the description reinforces this with 'Takes no arguments.' No additional parameter meaning is needed or missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise verb+resource ('lists the templates saved in the user's account, with the id each one needs') and separates itself from siblings by noting that create_dataset and list_datasets take a template_id instead. The opening sentence even establishes the SheetRender domain so the agent understands what a template is here.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit trigger condition ('Call it first whenever the user refers to a template by name') plus the concrete alternative behavior it enables: mapping a name to an id that 'every other tool here takes'. This is a clear when-to-use rule with the tool's role in the workflow spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
SheetRender turns HTML templates plus spreadsheet rows into rendered PDFs. This tool renders a single PDF from HTML you supply and returns the path to the saved file.
Use it for one-off documents — an invoice, a report, a certificate — where you are writing the markup yourself. Use render_template instead when the user already has a saved template.
html must be a complete HTML document (, , ) with all CSS inline in a tag: external stylesheets, fonts and scripts are not fetched. Use @page and mm/cm units for print layout.
data keys become Jinja template variables, so passing {"total": "42.00"} lets the HTML say {{ total }}. Jinja loops and conditionals work too. Omit data if the HTML has no placeholders.
Two server limits to plan for: HTML over 2 MB is rejected, measured both on what you send and on the result after data is substituted in, so keep large tables paginated rather than emitting one enormous document; and accounts on the free plan get a "Made with SheetRender" footer added to every PDF, which is expected, not a bug — mention it if the user seems surprised.
Returns the temp-file path and size; PDFs under 512 KB are also attached inline.
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | Template variables as a flat JSON object. Each key becomes a Jinja variable, so {"customer": "Acme"} makes {{ customer }} available in the HTML. | |
| html | Yes | A complete HTML document with inline CSS. May contain Jinja placeholders filled from `data`. | |
| page_settings | No | Optional page setup for the PDF. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It transparently discloses that external resources are not fetched, that HTML over 2MB is rejected (including after substitution), that free accounts get a footer, and that return includes path/size plus inline attachment for small PDFs. This exceeds expectations for behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear paragraphs. Each sentence earns its place: purpose, usage (with alternative), HTML requirements, data behavior, server limits, and return format. It is detailed but not repetitive; complexity is handled without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all necessary aspects for correct use: input requirements, template variable mechanics, output behavior, error conditions (2MB limit), and an environmental quirk (free-plan footer). It is fully self-sufficient even without annotations or output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema coverage, the description adds substantial meaning beyond the schema: it explains Jinja variable substitution with a concrete example, confirms loops/conditionals work, clarifies that data can be omitted, and details page_settings usage in plain terms. This significantly aids correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: rendering a single PDF from user-supplied HTML and returning the saved file path. It also distinguishes itself from render_template by explicitly saying when to use which, making it easy for an agent to select correctly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool ('one-off documents... writing the markup yourself') and when to use the alternative (render_template when a saved template exists). It also warns about size limits and the free-plan footer, covering both usage context and potential pitfalls.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
SheetRender turns HTML templates plus spreadsheet rows into rendered PDFs. This tool renders one PDF from a template already saved in the user's account and returns the path to the saved file.
Use it when the user wants a document in their existing design. Get template_id from list_templates. Use render_pdf instead when you are writing the HTML yourself.
data supplies one row's worth of values: each key becomes a Jinja variable in the template's HTML. To render a PDF for every row of a spreadsheet, load the rows with create_dataset or upload_dataset and run create_batch_job rather than calling this repeatedly.
Omit page_settings to keep the template's own saved page setup — passing it overrides that for this render only.
Free-plan accounts get a "Made with SheetRender" footer on the PDF, same as render_pdf — expected, not a bug.
Returns the temp-file path and size; PDFs under 512 KB are also attached inline.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Template variables as a flat JSON object. Each key becomes a Jinja variable, so {"customer": "Acme"} makes {{ customer }} available in the HTML. | |
| template_id | Yes | Template id from list_templates. | |
| page_settings | No | Optional page setup for the PDF. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: it discloses the free-plan watermark ('expected, not a bug'), the return payload (temp-file path and size, inline attachment under 512 KB), and the override semantics of page_settings. These are behaviors an agent cannot infer from the schema and would otherwise be surprised by.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short paragraphs, each doing distinct work: what it does, when to use it vs alternatives, what data means, and the page_settings override plus return/watermark notes. Front-loaded with the core purpose and no filler sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters, nested objects, and no output schema, the description covers selection, sibling routing, the single-row constraint, override behavior, and the return value including the free-plan watermark. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents data as Jinja variables and page_settings fields, making 3 the baseline. The description adds genuine meaning beyond the schema by stating that `data` supplies exactly one row's worth of values and that omitting page_settings preserves the template's saved setup while passing it overrides only for this render.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('renders one PDF from a template already saved in the user's account') and explicitly contrasts with the sibling render_pdf ('Use render_pdf instead when you are writing the HTML yourself'). An agent can distinguish this from render_pdf, design_template, and create_batch_job without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Names the conditions for use ('when the user wants a document in their existing design'), the source of the required id ('Get `template_id` from list_templates'), the alternative tool for a different case (render_pdf), and the escalation path for multi-row output (create_batch_job after create_dataset/upload_dataset). This is explicit when/when-not/alternatives coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
SheetRender turns HTML templates plus spreadsheet rows into rendered PDFs. This tool uploads a local .csv or .xlsx file as a dataset a batch job can render, and returns the dataset id plus the column keys.
Use it when the user points at a file they already have — an export, a spreadsheet they attached, something you just wrote to disk. Use create_dataset instead when you are holding the rows as JSON: it avoids writing a file only to read it straight back.
file_path is a path on the machine running this MCP server, which is the user's machine, not SheetRender's. The first row must be the header. Other spreadsheet formats (.xls, .ods, .numbers) and .pdf are not parsed — convert to .csv or .xlsx first.
Limits: 20 MB per file and 500,000 cells; larger data has to be split across several datasets and jobs. Uploading is free; only rendering counts against the account's plan.
Returns the dataset id and each column's sanitized key — the name the template's placeholders, filename_template and group_by use, which is often not the header text verbatim ("Invoice No" becomes invoice_no).
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Path to a .csv or .xlsx file on the user's machine. Absolute is safest; `~` is expanded. | |
| template_id | Yes | Template id from list_templates. The dataset lands in that template's project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and meets it: it discloses that file_path is on the user's machine rather than SheetRender's, that the first row must be the header, which formats are rejected, the 20 MB / 500,000-cell limits, and the billing nuance (upload free, rendering counts against the plan).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then separated paragraphs for usage, parameter semantics, limits, and return values. Length is justified by the amount of genuinely useful constraint information, and no sentence is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Though no output schema exists, the description describes the return values (dataset id plus each column's sanitized key) and covers the limits, format restrictions, and machine context an agent needs to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters. The description still adds real meaning beyond it: file_path lives on the user's machine, its format constraints and limits, and that the returned key is the sanitized name used by placeholders, filename_template, and group_by.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("uploads a local .csv or .xlsx file as a dataset a batch job can render") and explicitly contrasts with the sibling create_dataset. An agent can tell this apart from create_dataset without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit when-to-use trigger ("when the user points at a file they already have") plus a named alternative and its selecting condition ("Use create_dataset instead when you are holding the rows as JSON"). Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.4create_batch_job1 field changedInput schema / properties / dataset_id / descriptionPrevious value: -"Id of a dataset already uploaded to the same SheetRender project."New value: +"Dataset id from create_dataset, upload_dataset or list_datasets. It must belong to the same template's project."create_datasetdesign_templateget_designlist_datasetsupload_datasetv0.1.2create_batch_jobget_documentget_joblist_templatesrender_pdfrender_templateScored across 11 tools
Most tools are clearly distinct: render_pdf vs render_template (write HTML yourself vs use saved template), create_dataset vs upload_dataset (JSON rows vs local file), and get_job vs get_document (job status vs PDF download) are all explicitly cross-referenced. The only mild overlap is between get_design/template design tools and the job/polling tools, but descriptions draw the lines well.
Every tool follows a consistent snake_case verb_noun pattern: get_design, render_pdf, list_templates, design_template, get_job, render_template, create_dataset, upload_dataset, list_datasets, create_batch_job, get_document. No mixed conventions or vague verbs.
11 tools is well-scoped for a template/PDF rendering service, covering the full workflow (list, render, design, dataset creation, batch jobs, document retrieval) without redundancy or bloat.
The surface covers the core lifecycle: template discovery, single and batch rendering, dataset creation/upload/listing, job polling, and document download. Minor gaps exist — no delete/update operations for templates or datasets, and no explicit cancel_job tool despite job statuses mentioning 'cancelled' — but agents can work around these.
Generate HTML to PDF documents in bulk or single — raw replacements or based on conditions, loops
JSON in, PDF out. Render invoices, certificates, reports and cards from a template and a payload.
Cloud PDF generation from HTML, CSS and XSL-FO, with PDF/A and PDF/UA support.
Render PDFs from templates you design once: list templates, check the data shape, preview, render.
