Document API for AI-native software: render PDFs, e-sign, PAdES-seal, and verify.
Ask Kamy Brain a question about Kamy usage, templates, plans, or errors. Sends the question to Kamy's public assistant endpoint and returns a paragraph answer.
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes | The question to ask Kamy about — how to render a template, why a render failed, what plan to pick, etc. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only and non-destructive. The description adds that it sends the question to a public assistant endpoint and returns a paragraph answer, providing useful context about the network call and output format beyond the annotations.
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 a single, front-loaded sentence that states the purpose, mechanism, and output without any wasted words. It is appropriately sized for a simple tool.
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 one-parameter tool with no output schema, the description covers the tool's purpose, what kinds of questions to ask, and what the response format is (a paragraph answer). Annotations cover safety, so the overall context is complete.
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%: the 'question' parameter is fully described with examples ('how to render a template, why a render failed, what plan to pick'). The tool description's topic list overlaps with the schema examples and adds no new parameter-level semantics, 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 uses a specific verb ('Ask'), names the resource ('Kamy Brain'), and specifies the topics ('usage, templates, plans, or errors'). It clearly distinguishes this from all sibling tools, none of which are Q&A-oriented.
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 identifies when to use the tool by listing question categories, and the context makes it obvious that it is for informational queries. It does not explicitly name alternatives, but no sibling tool provides a competing assistant Q&A function, so the guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cryptographically sign an output your agent produced — a PDF, report, code patch, dataset, email — so a third party can later confirm those exact bytes are the ones that were recorded, unmodified. Pass content_text or content_base64 and Kamy hashes the bytes for you; pass content_sha256 alone when the content itself must never leave your environment. Returns { attestation_id, content_sha256, signature, recorded_at, verify_url } — hand verify_url to whoever needs to check the artifact. This proves the bytes match what this account recorded at that time; it makes no claim about whether the content is correct. Requires a Kamy API key.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Up to 20 free-form labels. | |
| run_id | No | Your identifier for the agent run this artifact belongs to. Pass the same run_id across attestations and agent-action records to build one provenance chain readable via get_provenance_chain. | |
| feature | No | Product area or pipeline name, for grouping attestations. | |
| metadata | No | Arbitrary JSON stored alongside the attestation (model, source URL, reviewer, ...). | |
| content_text | No | UTF-8 text artifact. Convenience input: this MCP server base64-encodes it locally and sends it as content_base64 — no other transformation is applied. Supply exactly one of content_sha256, content_base64, or content_text. | |
| artifact_type | Yes | What kind of output this is, e.g. 'pdf', 'report', 'code_patch', 'dataset', 'email', 'llm_output'. Free-form label used for filtering later. | |
| parent_sha256 | No | content_sha256 of the preceding record in the chain, when this artifact was derived from an earlier one. | |
| content_base64 | No | Base64-encoded artifact bytes. Use for binary output (PDF, image, archive). Supply exactly one of content_sha256, content_base64, or content_text. | |
| content_sha256 | No | SHA-256 of the artifact bytes, when you'd rather not send the content itself. Supply exactly one of content_sha256, content_base64, or content_text. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses behavioral traits beyond the annotations: it explains the hashing process ('Kamy hashes the bytes for you'), the security nuance (content never leaves when using sha256), and the scope of proof ('makes no claim about whether the content is correct'). Annotations are readOnlyHint=false, destructiveHint=false, which are correctly non-contradictory – the tool writes a new attestation but is not destructive. No annotation contradiction.
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 two sentences long and front-loads the core purpose. Every sentence adds value: the first covers purpose and usage modes, the second covers the return value and caveat. Slightly verbose in the first sentence listing artifact types (PDF, report, code patch, etc.), but justified for making the tool's scope concrete.
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 the tool's moderate complexity (9 parameters, 1 required, nested objects), the description is complete: it explains how to use the three content parameters, what the response contains, and what the attestation does and does not guarantee. No output schema exists, but the description explicitly lists the return fields (attestation_id, content_sha256, signature, recorded_at, verify_url) and their purpose.
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 adds significant value beyond the schema: it explains the three mutually exclusive content inputs (content_text, content_base64, content_sha256) and their trade-offs, clarifies that content_text is automatically base64-encoded locally, and describes the return value structure. It also imparts the concept of building a provenance chain via parent_sha256 and run_id, which is not explicit in the schema.
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 uses specific verbs like 'cryptographically sign' and 'hash' with a clear resource (an output artifact). It distinguishes itself from siblings like 'verify_attestation' and 'record_agent_action' by focusing on signing for third-party verification, and includes a concrete list of artifact types (PDF, report, code patch, etc.).
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 explicitly states when to use the tool (to sign an output for third-party verification) and provides a key decision point: pass content_text/content_base64 if content can leave, or content_sha256 alone if it must stay in-environment. It doesn't explicitly name sibling tools as alternatives (e.g., 'verify_attestation' for verification, 'record_agent_action' for logging actions), but the guidance is clear enough for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fan one already-rendered PDF out to up to 100 independent signers in a single call — the 'send this NDA to everyone on the list' path. Each signer gets their own request, their own sign link and their own invitation email, but they all share one source render, so only one document is produced and stored. Choose create_envelope instead when the recipients are signing the SAME document together and you need routing, ordering and one envelope status; choose this when they are unrelated parties each signing their own copy. Duplicate signer emails within one batch are rejected up front with 422. Per-signer failures do not abort the batch: the response is { bulkId, count, successCount, failureCount, results } in input order, each row either ok with signatureId and signUrl or ok:false with a reason, and the call returns 207 when any row failed. Consumes one signature from the monthly quota PER signer (free tier: 10 per month, then per-signature billing), so a large batch can exhaust a small plan part-way through and the remaining rows come back failed. Requires a Kamy API key with the signatures:write scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| message | No | Shared invite message. `{{signerName}}` is substituted per recipient. | |
| signers | Yes | 1–100 signers. Duplicate emails are rejected up front with 422. | |
| position | No | One signature rectangle in PDF points (origin bottom-left) shared by every signer. | |
| renderId | Yes | Render UUID every signer receives. One render, one storage object, many requests. | |
| expiresIn | No | Sign-link lifetime in seconds. Min 1 hour, max 30 days. Defaults to 7 days. | |
| reminderCadenceHours | No | Auto-reminder cadence in hours, shared across the batch. Up to 3 reminders. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false (not read-only), openWorldHint=true, destructiveHint=false. The description goes well beyond by detailing: duplicate emails rejected with 422, per-signer failures return 207 with partial results, consumes one signature per signer from quota with free tier limits, requires signatures:write scope, and even describes the response shape. No contradictions with annotations.
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 a single paragraph of 6 sentences, each serving a distinct purpose: core behavior, comparison with sibling, duplicate handling, error handling with response shape, quota consumption, and auth requirements. Front-loaded with the main use case. Zero wasted words.
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 the tool's complexity (nested signers object, position, 6 parameters, partial-failure semantics, quota impact, auth scope), the description covers all critical aspects. No output schema exists, but the response structure is described inline. The sibling list shows 50+ tools, yet the description uniquely positions this tool vs create_envelope. Complete for an agent to decide and invoke 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% with descriptions for each parameter. The description adds meaning beyond the schema: explains that `message` supports `{{signerName}}` substitution, that `signers` duplicates are rejected with 422, that `position` is in PDF points with bottom-left origin and shared by every signer, and that `expiresIn` defaults to 7 days and `reminderCadenceHours` is shared across the batch. No schema gaps remain.
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 fans one PDF to up to 100 independent signers, each getting their own request, link, and email. It distinguishes this from create_envelope, which is for joint signing with routing. The verb 'fan' and resource 'one PDF to many separate signers' is specific and immediately understandable.
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 says when to use ('send this NDA to everyone on the list') and when not ('Choose create_envelope instead when the recipients are signing the SAME document together'). No usage gaps; the description directly contrasts the sibling tool and provides clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a file you already hold — .docx, .xlsx or .csv — into a PDF, preserving its existing content. Pass the bytes base64-encoded together with the original filename, which is what the API uses to detect the input type. This is the inbound direction: it consumes an existing document, whereas render_docx / render_xlsx / render_pptx GENERATE new documents from structured data, and render_pdf builds one from a template. Returns a stored render { id, url, bytes, durationMs, name } whose id can be fed straight into merge_pdfs, split_pdf, edit_pdf, create_signature_request or create_envelope. Counts one render against the monthly quota. Files over 10 MB are refused by this tool because the bytes travel through the tool call. Requires a Kamy API key with the render scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Label for the resulting render row. Defaults to the source filename. | |
| filename | Yes | Source filename including its extension — the route detects the input type from it. Must end in .docx, .xlsx or .csv. | |
| fileBase64 | Yes | Base64-encoded bytes of the source file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses several behavioral aspects beyond annotations: the direction (inbound conversion vs. generation), the file size limit (10 MB), quota impact (counts against monthly render quota), and authentication requirement (Kamy API key with `render` scope) with a fallback behavior. Annotations are minimal (readOnlyHint: false, destructiveHint: false), so the description carries the full burden and does so thoroughly, far exceeding what annotations alone provide.
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 a single paragraph of 6 sentences, each serving a distinct purpose: defining the action, explaining how input type detection works, distinguishing from generator siblings, describing the return value and downstream usage, noting quota and size constraints, and specifying authentication requirements. Nothing is redundant, and all information is essential and well-ordered, earning every sentence its place.
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, the description provides a complete picture: it lists the return fields (id, url, bytes, durationMs, name), explains the conversion direction and constraints, covers quota and authentication, and links to sibling tools for downstream operations. The parameter richness (3 params, 100% coverage) and sibling context are fully leveraged to make the description self-sufficient for agent understanding.
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 baseline is 3, but the description adds significant value by explaining the relationship between filename and input type detection, clarifying that the name parameter defaults to the source filename, and describing the purpose of fileBase64 (pass bytes base64-encoded). This transforms basic schema definitions into actionable guidance, fully compensating for any potential ambiguity.
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 converts .docx, .xlsx, or .csv files to PDF, specifying the verb 'Convert', the resource 'file', and the output format. It distinguishes this tool from siblings like render_docx (which generate new documents from structured data) and render_pdf (builds from a template), making its purpose unambiguous and unique.
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 versus alternatives, naming render_docx, render_xlsx, render_pptx, and render_pdf as tools that generate documents rather than convert existing ones. It also explains that the returned id can be fed into merger/split/sign tools, and flags the constraint that files over 10 MB are refused because bytes pass through the tool call. This covers both when-to-use and when-not-to-use scenarios comprehensively.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a single PDF to 2–10 signers as one envelope. This is the multi-signer counterpart to create_signature_request, which handles exactly one signer — the API rejects an envelope with fewer than two recipients, so pick the tool by signer count. routing 'parallel' (default) emails everyone at once and each signs independently; routing 'sequential' emails only the lowest-order recipient and activates the rest one at a time as each preceding signer finishes, which is what you want for approve-then-countersign chains. The source is either a render you own (renderId) or a PDF fetched from a public URL (pdfUrl) — supply exactly one. Pass preview: true to create the envelope and get every sign URL back WITHOUT sending any email and WITHOUT consuming quota; do that first if you are unsure about field placement. A real send emails the recipients immediately and consumes one signature from the monthly quota PER recipient (free tier: 10 signatures/month, then per-signature billing). Returns { envelope, recipients: [...] } with a sign_url per recipient. Requires a Kamy API key with the signatures:write scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| pdfUrl | No | Publicly fetchable PDF URL. Kamy downloads it and stores it as a render first. Supply exactly one of renderId or pdfUrl. | |
| message | No | Message included in every invitation email. | |
| preview | No | When true, creates the envelope and returns every sign URL WITHOUT emailing anyone and without consuming signature quota. Use it to check placement and routing before the real send. | |
| routing | No | 'parallel' (default) emails everyone at once and each signs independently. 'sequential' emails only the lowest-order recipient; the rest are created with status 'waiting' and activated one at a time as the preceding signer completes. | parallel |
| ccEmails | No | Up to 10 observers CC'd on the invitations. Not signers. | |
| position | No | Default signature placement in PDF points, origin bottom-left. | |
| renderId | No | UUID of a completed render owned by this account. Supply exactly one of renderId or pdfUrl. | |
| expiresIn | No | Sign-link lifetime in seconds. Min 1 hour, max 30 days. | |
| recipients | Yes | 2–10 signers. The route rejects a single recipient — use create_signature_request for one signer. | |
| placedFields | No | Up to 100 sender-placed form fields for signers to complete. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint false, destructiveHint false, openWorldHint true), the description discloses that real send emails immediately and consumes quota per recipient (with free tier specifics), that preview mode avoids both, that API key scope is required, and details routing behavior (e.g., sequential activates one at a time). This fully informs the agent of side effects and prerequisites.
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 rich but well-structured, starting with the core purpose, then sibling distinction, routing, source, preview, quota, auth, and return format. Every sentence serves a purpose. It is slightly verbose for a tool with many parameters, but the details justify the length. Front-loading is effective.
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 10 parameters, nested objects, 30 sibling tools, and no output schema, the description covers purpose, usage guidelines, routing modes, source selection, preview, quota, auth, and return shape. Missing explicit error conditions or rate limits, but those are likely standard API concerns. The provided information is sufficient for correct tool invocation.
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 baseline is 3. The description adds meaningful context beyond schema descriptions: it explains the mutual exclusivity of renderId and pdfUrl, clarifies how routing interacts with recipient order, and elaborates on the preview parameter's effect. However, some schema descriptions (e.g., for recipients min/max) already convey much of this, so the added value is moderate.
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 'Send a single PDF to 2–10 signers as one envelope' – a specific verb and resource. It explicitly distinguishes itself from the sibling tool create_signature_request by noting the signer count threshold (2–10 vs exactly one), making the purpose unambiguous and differentiated.
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: 'This is the multi-signer counterpart to create_signature_request' and 'pick the tool by signer count.' It explains routing modes ('parallel' vs 'sequential') with concrete use cases (e.g., 'approve-then-countersign chains'), and recommends using preview mode when uncertain. No alternative exclusion needed; it covers when to use this tool and how to configure it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set up a recurring render: a cron expression, a template, and where each document goes. Use this instead of render_pdf when the user wants a document produced repeatedly on a calendar — a weekly report, a monthly invoice run — so nothing has to stay running. Delivery channel is 'email' or 'whatsapp' (recipients required) or 'download' (stored only; retrieve later with list_renders). The cron is evaluated in the given IANA timezone, and how often it may fire is plan-gated: at least 60 minutes apart on Free, 15 on Starter, 5 on Pro and above — a tighter expression is rejected with a validation error naming the limit. Every firing spends one render from the monthly quota, so a frequent schedule can exhaust a small plan on its own. Returns the created schedule including its id and next_run_at.
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | Template data, used verbatim on every firing. Defaults to {}. | |
| name | Yes | Human label for this schedule, shown in the dashboard. | |
| channel | Yes | Where each rendered document goes. 'download' just stores it (find it later with list_renders); 'email' and 'whatsapp' require recipients. | |
| enabled | No | Defaults to true. Create it disabled to set it up now and start it later. | |
| options | No | Render options passed straight through to the render, in the nested /v1/render shape, e.g. { format: 'letter', margin: { top: '20mm' } }. | |
| schedule | Yes | Standard 5-field cron expression, e.g. '0 9 * * 1' for 09:00 every Monday. Rejected with a validation error if it fires more often than the plan's minimum interval. | |
| template | Yes | Template slug or UUID rendered on every firing. Same values render_pdf accepts. | |
| timezone | No | IANA timezone the cron expression is evaluated in, e.g. 'Asia/Dubai'. Defaults to UTC. | |
| recipients | No | Email addresses or phone numbers, matching the channel. Required and non-empty for email and whatsapp; ignored for download. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint=false, etc.), but the description fully compensates by disclosing key behaviors: every firing consumes a render quota, plan-gated minimum intervals, rejected expressions produce validation errors, and the return includes id and next_run_at. This is comprehensive for a creation 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 a single, well-structured paragraph that front-loads the core purpose ('Set up a recurring render') and progressively adds details. Every sentence conveys essential information without redundancy, earning its place.
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 the tool has 9 parameters, 4 required, nested objects, and no output schema, the description is remarkably complete. It covers when to use the tool, how parameters interact, plan limits, quota implications, and what the response contains. No critical gaps are present for an agent to use this tool 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 adds value beyond the schema by explaining the frequency limitations in context (plan-gated intervals), the relationship between channel and recipients, and the behavior of enabled (create disabled to start later). Minor deduction because the description doesn't elaborate on the options parameter's nested structure beyond what the schema says.
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 creates a recurring render with a cron expression, template, and delivery configuration. It explicitly distinguishes itself from render_pdf by specifying when to use this tool instead, making the purpose highly specific and actionable.
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 ('when the user wants a document produced repeatedly on a calendar') and contrasts it with the sibling render_pdf. It also explains delivery channel options, plan-gated frequency limits, and quota implications, helping the agent decide correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a previously rendered PDF to a signer for e-signature when a Kamy API key is configured. Without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| message | No | Optional message rendered in the email invitation body. | |
| ccEmails | No | Up to 10 observer addresses CC'd on the invite and the completion notice. Not signers themselves. | |
| position | No | Optional sender-chosen signature placement in PDF points (72 dpi, origin bottom-left). Defaults to bottom-right of the last page sized 220×64 pt; when omitted, the signer can drag the placeholder on the sign page. | |
| renderId | Yes | Render UUID returned by render_pdf or any /v1/render call. The render's PDF is the document the signer will receive. | |
| expiresIn | No | How long (seconds) the sign link stays valid. Defaults to 30 days. Min 1 hour, max 30 days. | |
| authMethod | No | Identity-verification mode. `link` (default) — possession of the secret URL is the only check. `email_otp` — sign page renders a 6-digit OTP gate; code emailed to `signerEmail`. `sms_otp` — same gate, code texted to `signerPhone` (which must then be supplied). Recommend `email_otp` for higher-value transactions. | |
| signerName | Yes | Recipient full name. Must be typed verbatim by the signer to confirm intent. | |
| signerEmail | Yes | Recipient email address. | |
| signerPhone | No | E.164 phone number. Required when `authMethod` is `sms_otp`; ignored otherwise. Example: `+14155551234`. | |
| placedFields | No | Up to 100 sender-defined fillable fields stamped onto the PDF at sign time. Use for flat PDFs that don't ship AcroForm widgets. Names must be unique. | |
| requireStamp | No | Require the signer to upload a company stamp / seal alongside their personal signature (UAE, KSA, JP, KR, IN, CN B2B workflows). Server refuses to seal without one. | |
| signOnEveryPage | No | When true, the server stamps the signer's signature on every page of the source PDF instead of only the configured position. Common B2B contract pattern. | |
| signatureTemplateId | No | Apply a signature template's defaults (placedFields, position, message, expiresIn, ccEmails). Request-level fields override the template. | |
| reminderCadenceHours | No | When set (24–168), the auto-reminder cron resends the invite every N hours while the request stays pending, up to 3 reminders. Omit for no auto-reminders. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as non-read-only and non-destructive; the description adds the prerequisite of a Kamy API key and the conditional behavior of returning dashboard setup instructions without a key. This is useful behavioral context that goes beyond the annotations.
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 two sentences, front-loaded with the main action and a conditional. Every word earns its place; there is no redundancy or 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?
The tool is complex (14 params, nested objects, no output schema), and the description is minimal. It explains the no-key fallback but not the success return value or the overall workflow (e.g., what happens after sending). The schema fills in parameter details, but the description should provide more behavioral context for such a complex 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%, so the baseline is 3. The description adds no parameter-level details beyond 'previously rendered PDF' (implied renderId) and 'signer' (implied signerEmail/Name), so it does not augment the schema's already-thorough parameter documentation.
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 specific action ('Send a previously rendered PDF to a signer for e-signature') and resource, and the condition about 'when a Kamy API key is configured' adds useful scoping. It distinguishes this tool from siblings by emphasizing the input is a rendered PDF and the purpose is e-signature sending.
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 gives clear context: use when you have a previously rendered PDF and a Kamy API key is configured, and warns about the fallback when no key is set. It does not name explicit alternatives or exclusions, but the context is strong enough for an agent to select this tool appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new custom PDF template owned by this account: a name, a unique slug, a Handlebars/HTML body, and optional CSS and JSON Schema. The slug is what render_pdf then takes as template. Custom templates are a paid feature — on the Free plan this returns 403 FORBIDDEN before anything is created. The slug must be unique within the account and must not collide with a built-in system slug (invoice, receipt, quote, …); both cases come back 422, and the fix for an already-taken slug is update_template rather than a retry. A brand-new template has no published version, so it renders straight from what you supply here — publish_template only becomes necessary once you start cutting versions. Requires a Kamy API key with the templates:write scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| css | No | Stylesheet applied at render time. Max 1 MB. | |
| html | Yes | Handlebars/HTML body of the document. Max 5 MB. | |
| name | Yes | Human-readable template name. | |
| slug | Yes | Stable identifier the render tools take as `template`. Unique per account, and it may not collide with a built-in system slug (invoice, receipt, quote, …) — both cases are rejected with 422. | |
| tags | No | Up to 10 free-form labels. | |
| schema | No | JSON Schema describing the data payload the template expects. Defaults to {}. | |
| isPublic | No | When true, other accounts can list and render it. Defaults to false. | |
| description | No | What this template is for. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false, destructiveHint=false. The description adds extensive behavioral context: it's a paid feature (403 on Free), name collision handling (422 with remediation), no published version on first creation, and requires a 'templates:write' scope API key. All of this goes well beyond the annotations alone.
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 a single paragraph of 6 sentences, which is efficient and front-loaded with the core action. Each sentence adds value. It could potentially be split into a short intro plus usage notes, but it's not overly verbose.
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 fully covers the tool's behavior for 8 parameters, 3 required, nested objects (schema), no output schema (not needed since creation returns a version or status). It explains error cases, auth prerequisites, and the versioning lifecycle, making it complete for a complex tool with many siblings.
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 baseline is 3. The description adds meaning by explaining the purpose of the slug (what render_pdf uses) and the relationship between create_template and publish_template. However, it doesn't elaborate on all 8 parameters beyond what the schema says; a bit more on 'isPublic' or 'tags' could push this to 5.
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 opens with 'Create a new custom PDF template owned by this account' which is a specific verb and resource. It lists the key fields (name, slug, HTML body, optional CSS and JSON Schema) and explicitly distinguishes the tool's outcome from siblings like update_template and publish_template.
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 gives explicit guidance on when to use this tool versus update_template (alternative for a taken slug) and publish_template (not needed for first version). It also states the Free plan returns 403, and explains error conditions for duplicate/conflicting slugs with specific HTTP codes and remediation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register an HTTPS endpoint that Kamy POSTs to when work finishes, so a long render or an e-signature does not have to be polled. Use this when the caller owns a server that can receive callbacks; use get_job or list_renders when it cannot. The response includes a one-time signing secret used to verify delivery signatures — it is shown here and never again, so surface it to the user immediately and tell them to store it. Defaults to the render.completed and render.failed events; the full set is render.completed, render.failed, signature.signed, signature.voided, signature.expired, signature.envelope_completed, signature.envelope_voided, test.ping, and any other string is accepted so new events can be subscribed to without an upgrade. Endpoint URLs on private, loopback, link-local or cloud-metadata hosts are rejected at registration, so a localhost tunnel will not work — use a public URL.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | HTTPS endpoint Kamy POSTs each event to. Private, loopback, link-local and cloud-metadata hosts are rejected at registration time, so localhost and 10.x/192.168.x addresses will not work. | |
| events | No | Event names to receive. Defaults to ["render.completed", "render.failed"]. Known events: render.completed, render.failed, signature.signed, signature.voided, signature.expired, signature.envelope_completed, signature.envelope_voided, test.ping. | |
| enabled | No | Defaults to true. Register it disabled to wire it up before switching it on. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show `destructiveHint: false`, which aligns with the description's non-destructive nature. The description adds transparency beyond annotations by disclosing the one-time signing secret delivery (critical for agent behavior), default events, and host restrictions (private/loopback/link-local/cloud-metadata). It doesn't explicitly state idempotency behavior or whether duplicate registrations are allowed, which would be helpful, but the provided details are strong.
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 concise at 5-6 sentences, front-loaded with the core purpose and usage guidelines. Each sentence provides unique value: purpose, usage alternative, secret disclosure, default events, and URL restrictions. It could be slightly more structured (e.g., bullet points for events), but it is well-organized and avoids redundancy with the schema. The length is appropriate for the tool's moderate complexity.
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 the tool has 3 parameters (100% schema coverage) and no output schema, the description covers purpose, usage guidelines, behavioral details (secret, host restrictions), and parameter context (default events). It lacks explicit idempotency or error handling information, but for a registration tool, the description is substantially complete. The sibling tools (e.g., `test_webhook`) are not referenced, but the description already clarifies the tool's role.
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 input schema has 100% description coverage, providing clear meaning for all three parameters (`url`, `events`, `enabled`). The description adds value by explaining the one-time secret and default events, which the schema does not cover. It does not reiterate parameter descriptions from the schema, which is appropriate. The description's mention of wildcard event acceptance ('any other string is accepted') is not in the schema, adding critical context.
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 that the tool registers an HTTPS endpoint for Kamy to POST to when work finishes, distinguishing it from polling-based approaches. It explicitly names the verb 'register' and the resource 'HTTPS endpoint', making the purpose unambiguous. The sibling tools list includes `list_webhooks` and `test_webhook`, but the description's focus on creating a new subscription sets this tool apart.
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 usage guidance: 'Use this when the caller owns a server that can receive callbacks' and 'use get_job or list_renders when it cannot'. This directly contrasts the tool's use case with alternatives, offering a clear when-to-use and when-not-to-use rule. It also warns about endpoint URL restrictions, further guiding appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a recurring schedule so it stops firing. There is no undo and no trash — recreate it with create_schedule if it is deleted by mistake, so confirm with the user before calling this on a schedule you did not just create. If the intent is only to pause it, do not use this tool: a schedule can be switched off and back on again via its enabled flag on the REST endpoint (PATCH /v1/schedules/{id}), which this MCP surface does not expose. Documents already produced by past firings are unaffected and remain available through list_renders. Returns { deleted: true }, or 404 if the id does not belong to this account.
| Name | Required | Description | Default |
|---|---|---|---|
| schedule_id | Yes | Schedule id (UUID) from create_schedule or list_schedules. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the description adds value by emphasizing no undo and no trash, and clarifies that past documents are unaffected. However, it does not elaborate on authentication requirements or rate limits, which could be relevant for a destructive operation. The description aligns with and enriches annotations.
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 sentences, each serving a distinct purpose: permanent deletion warning with recovery path, alternative to pausing, and effect on past documents with return value. Front-loaded with the core action and consequence.
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 the simple single-parameter schema and the presence of destructiveHint annotation, the description fully covers all aspects: input provenance, safety warnings, alternative behavior, and return format. No gaps remain.
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 baseline is 3. The description adds value by explaining that the schedule_id comes from `create_schedule` or `list_schedules`, which clarifies the parameter's provenance beyond the schema's 'UUID' description. This is helpful context, earning a 4.
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 verb 'delete' and the resource 'recurring schedule', and explicitly distinguishes it from pausing (via the `enabled` flag) and from `create_schedule` for recovery. It differentiates from siblings like `list_schedules` and `create_schedule` by focusing solely on deletion.
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?
Provides explicit guidance on when to use (permanent deletion intent) and when not to use (if only pausing is needed, do not use this tool). Offers a concrete alternative action (PATCH /v1/schedules/{id} via `enabled` flag) and recommends user confirmation before calling on pre-existing schedules.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Modify an existing PDF: fill AcroForm fields by name, stamp text at absolute coordinates, or paint opaque boxes over regions. Operations apply in the order given, to either a render you own (renderId) or a PDF Kamy downloads from a public URL (pdfUrl) — supply exactly one. Use this when a document already exists and needs values or marks; use render_pdf when the document should be generated from a template instead. Nothing is overwritten: the source is untouched and the result is a NEW render whose id feeds directly into create_signature_request, create_envelope, merge_pdfs or split_pdf. Coordinates are PDF points with the origin at the BOTTOM-left. AcroForm values are flattened by default so they cannot be edited after signing. 'cover' paints an opaque rectangle over the region — it hides content visually but does NOT delete the underlying bytes, and the response carries a COVER_VISUAL_ONLY warning for every cover op. Anyone can still copy the text out from under the box. It is NOT redaction: never use it to hide secrets or personal data in a document you are about to hand out, and do not describe the result as redacted. There is no redaction operation — 'op: redact' is rejected with REDACTION_NOT_SUPPORTED. To remove sensitive data, regenerate the document without it. Returns { id, url, bytes, durationMs, name, warnings } — always read warnings, since out-of-range pages and unmatched field names are reported there rather than failing the call. Requires a Kamy API key with the render scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Label for the resulting render row. | |
| pdfUrl | No | Publicly fetchable URL of a PDF Kamy has never seen. Kamy downloads it, applies the operations and stores only the edited result — the source does not become a separate render, and the call costs one render either way. Supply exactly one of renderId or pdfUrl. | |
| renderId | No | UUID of an existing render owned by this account. Supply exactly one of renderId or pdfUrl. | |
| operations | Yes | 1–200 operations applied in the order given. 'fill_field' writes into an AcroForm widget; 'stamp_text' draws text at an absolute position; 'cover' paints an opaque rectangle over the region — it hides content visually but does NOT delete the underlying bytes, and the response carries a COVER_VISUAL_ONLY warning for every cover op. Anyone can still copy the text out from under the box. It is NOT redaction: never use it to hide secrets or personal data in a document you are about to hand out, and do not describe the result as redacted. There is no redaction operation — 'op: redact' is rejected with REDACTION_NOT_SUPPORTED. To remove sensitive data, regenerate the document without it. | |
| flattenFields | No | Bake AcroForm values into the page content stream after the fill_field ops so they can no longer be edited. Leave true before e-signing. Pass false only when something downstream still needs the live form. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false (mutation), openWorldHint=true (unexpected results possible), destructiveHint=false (source unchanged). The description adds crucial behavioral details: operations apply in order, source is untouched (a NEW render is created), cover does NOT delete underlying bytes and carries a COVER_VISUAL_ONLY warning, 'op: redact' is rejected with REDACTION_NOT_SUPPORTED. It also discloses auth requirements (Kamy API key with `render` scope) and warns about warnings carrying out-of-range pages/unmatched field names. No contradiction with annotations.
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 dense but not verbose; every sentence carries important information. It front-loads the core purpose and operations, then adds usage, then behavioral caveats, then parameter details. The only inefficiency is the near-verbatim repetition of the cover caveat in both the description and the operations schema item description, but that is defensible for clarity. At roughly 300 words, it is thorough yet focused.
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 the tool's complexity (three operation types, source selection, auth scope, warning handling), the description covers all necessary aspects: what the tool does, how to use it, behavioral side effects, failure modes (warnings, not hard errors), and relationships to sibling tools. No output schema exists, but the description lists the return fields ('{ id, url, bytes, durationMs, name, warnings }') and explains the significance of warnings. No gaps remain for an AI agent to make incorrect assumptions.
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 adds value by explaining the coordinate origin (BOTTOM-left), that 'flattenFields' defaults to true and why ('so they cannot be edited after signing'), and the 'cover' operation's visual-only nature. However, it could more explicitly tie each parameter to the operations array or clarify how to supply exactly one of renderId/pdfUrl inline. The extra detail lift it to a 4.
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 'Modify an existing PDF' and enumerates the three specific operations (fill AcroForm fields, stamp text, paint opaque boxes). It distinguishes itself from sibling tools like render_pdf ('use render_pdf when the document should be generated from a template instead'), and notes relationships to create_signature_request, create_envelope, merge_pdfs, and split_pdf. The verb–resource combination is precise and 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?
The description explicitly tells when to use this tool ('when a document already exists and needs values or marks') and when not to ('use render_pdf when the document should be generated from a template'). It also warns against using cover for redaction ('never use it to hide secrets or personal data'), and states the alternative for removing sensitive data ('regenerate the document without it'). The distinction between renderId and pdfUrl sources is clearly explained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract structured data from a PDF (invoice, receipt, contract, ID document, or any form). Returns the parsed JSON plus a public verify URL that proves the extraction matches the source. Use this when an agent needs to read an inbound document and act on it.
| Name | Required | Description | Default |
|---|---|---|---|
| template | Yes | Predefined template id. invoice/receipt for AP and POS docs, contract for legal agreements, id_document for passports/IDs, generic_form for anything else. | |
| source_url | No | Public URL to a PDF (preferred). One of source_url or source_base64 is required. | |
| source_base64 | No | Base64-encoded PDF bytes. Use when the source isn't publicly fetchable. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description directly contradicts the annotations. readOnlyHint is false, yet the description frames the tool as a read-only operation ('read an inbound document', 'Extract'), implying no side effects. This is a serious inconsistency that could mislead an agent about the tool's side effects.
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 two sentences long, front-loaded with the action and object, and every sentence serves a purpose: stating the function and providing usage guidance plus return value details. There is no 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?
The description explains return values (parsed JSON and verify URL) which is necessary since there is no output schema. It also covers typical input types. However, it omits any mention of side effects or persistence that the 'Ingest' title implies, and the read-only framing contradicts annotations, leaving key context incomplete.
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 input schema already provides 100% parameter coverage with descriptions for all three parameters. The description adds no extra parameter-level semantics beyond what the schema offers, so the baseline of 3 is 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?
The description opens with a specific verb+resource: 'Extract structured data from a PDF' and enumerates common document types (invoice, receipt, contract, ID document, any form). This clearly distinguishes it from sibling tools like render_pdf or verify_pdf_signature, which serve different purposes.
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 usage context: 'Use this when an agent needs to read an inbound document and act on it.' This tells the agent when to choose this tool, though it doesn't explicitly mention when not to use it or name alternatives. The guidance is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the text or the form fields back out of a document this account already rendered, without uploading anything. Pass type='text' (the default) for per-page text plus a joined fullText string, or type='fields' for the PDF's AcroForm field names, types and current values — the latter is how you discover what edit_pdf can fill in. Choose extract_document instead when the PDF came from outside Kamy or when you need AI-structured JSON against a schema; this tool is a plain mechanical read of an existing render, spends no render quota and no extraction credits. The render must have status 'success' or the call returns 409 RENDER_NOT_READY.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | 'text' (default) returns { pages: [{ page, text }], fullText, pageCount }. 'fields' returns the AcroForm fields as { name, type, value }. | |
| render_id | Yes | Render id (UUID) as returned by render_pdf, render_async/get_job, or list_renders. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: it is a 'plain mechanical read', requires no upload, spends no render quota or extraction credits, and returns a 409 error if the render is not successful. This fully discloses behavior beyond the annotations.
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 four sentences long and packs significant information without redundancy. It is front-loaded with the core action and gradually adds context. A minor improvement would be to further condense the last sentence about errors, but overall it is well-structured and efficient.
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 only two parameters (all documented) and no output schema, the description covers purpose, use cases, preconditions, return formats for both type variants, error scenarios, and quota/credit implications. It also differentiates from sibling tools. This is complete for a tool of this complexity.
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?
Although the schema already describes both parameters with 100% coverage, the description adds meaning by explaining the default for 'type' ('text'), detailing the return structure for each variant, and linking the 'fields' type to the sibling tool edit_pdf ('the latter is how you discover what edit_pdf can fill in'). This enriches the parameter understanding beyond the schema.
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 verb ('Read') and resource ('text or the form fields back out of a document this account already rendered'), with specific variants for 'text' and 'fields'. It explicitly distinguishes itself from the sibling tool extract_document, making the purpose 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?
The description provides explicit guidance on when to use this tool versus extract_document ('Choose extract_document instead when the PDF came from outside Kamy or when you need AI-structured JSON against a schema'). It also notes the prerequisite (render status must be 'success') and mentions that no quota or credits are consumed, helping the agent decide appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read everything about the authenticated Kamy account in one call: profile, plan and plan status, the plan's limits (renders per month, API keys, seats, custom templates, overage pricing, priority queue), month-to-date render usage, and whether documents rendered on this plan carry Kamy's own watermark. This is the only tool that answers any of those questions — there is no separate quota tool. Call it before render_batch, create_schedule, or any long series of renders: usage.renders.remaining is how many the API will still accept, and every render tool fails with 402 QUOTA_EXCEEDED once it hits zero, a failure nothing can recover from within the same calendar month. quota and remaining are null on unmetered plans, which means unlimited, not zero. Also check watermarkPolicy.appliedToRenders before generating something the user intends to send on: it is true on the free plan and cannot be turned off per render. Read-only, spends nothing, and works with any valid API key regardless of its scopes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive. The description adds critical behavioral context: that render tools fail with 402 QUOTA_EXCEEDED when quota is zero, that quota/remaining are null on unmetered plans (meaning unlimited), and that watermarkPolicy.appliedToRenders must be checked. Also notes it works with any valid API key regardless of scopes.
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 relatively long but every sentence adds value. It is front-loaded with the primary purpose. Could be slightly trimmed, but the density of useful information justifies the length.
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?
With no output schema, the description fully explains the return values: profile, plan, plan status, limits, usage, watermark. It covers edge cases (null on unmetered plans, watermark behavior) and explains the critical usage context for checking remaining quota. Complete for a complex, data-rich 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?
No parameters, so baseline is 4. The description compensates by explaining what the tool returns, but no parameter documentation is needed.
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 specifies that it reads everything about the authenticated Kamy account: profile, plan, limits, usage, and watermark. It explicitly states it is the only tool answering these questions, distinguishing it from all sibling tools.
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?
Provides clear when-to-use guidance: call it before render_batch, create_schedule, or any long series of renders to check remaining quota. Explains consequences of not checking (402 QUOTA_EXCEEDED). Does not explicitly list when not to use, but the context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one multi-signer envelope with every recipient in signing order — each with a live sign_url, status, recipient_order, expires_at and last_reminded_at — plus the envelope's own status and routing. This is the tool for 'who still has not signed?' after a create_envelope send; get_signature_request answers that for a single standalone request and returns no recipient list. Under sequential routing, recipients whose turn has not arrived show status 'waiting'. Read-only and spends no quota. Requires a Kamy API key with the signatures:read scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| envelopeId | Yes | Envelope ID returned by create_envelope. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations (readOnlyHint=true, destructiveHint=false). It states 'Read-only and spends no quota,' which reinforces the read-only nature. It reveals sequential routing behavior: 'Under sequential routing, recipients whose turn has not arrived show status "waiting".' It also discloses auth requirements: 'Requires a Kamy API key with the signatures:read scope; without a key, returns dashboard setup instructions.' No contradiction with annotations.
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 efficiently written, front-loading the main action and recipient details. Every sentence adds value (usage guidance, behavioral notes, auth requirements). It could potentially be tightened slightly (e.g., listing recipient fields could be implied), but it remains clear and not overly verbose. No wasted words.
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?
With no output schema, the description fully discloses what is returned: every recipient in signing order with fields (sign_url, status, recipient_order, expires_at, last_reminded_at) plus the envelope's own status and routing. It covers edge cases (sequential routing waiting status). Requires only one parameter with good schema coverage. The description is complete for an agent to safely invoke and understand the result.
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 describes envelopeId as 'Envelope ID returned by create_envelope.' The description adds no additional details about the parameter's format or constraints beyond the schema. It does imply usage context (the envelope should come from create_envelope), but this is already in the schema description. Baseline 3 is appropriate given full schema coverage.
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 'Fetch one multi-signer envelope with every recipient in signing order,' specifying the verb (fetch) and resource (multi-signer envelope with recipients). It explicitly distinguishes itself from the sibling tool get_signature_request, which 'answers that for a single standalone request and returns no recipient list.' This grounds the tool's purpose precisely among many similar tools.
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 gives explicit when-to-use guidance: 'This is the tool for "who still has not signed?" after a create_envelope send.' It also provides a clear alternative: 'get_signature_request answers that for a single standalone request and returns no recipient list.' This tells agents exactly when to choose this tool over a sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Poll an asynchronous render job started by render_async. Returns { jobId, status } where status is 'queued', 'processing', 'completed' or 'failed'; on 'completed' the response also carries render with the finished document's id, signed URL, size and duration, and on 'failed' it carries error with the reason. Poll every few seconds rather than in a tight loop — a typical render finishes in seconds, a heavy one can take a minute. If a job's signed URL has since expired, pass its render id to get_render for a fresh one. Read-only and spends no quota.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | The jobId render_async returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds rich behavioral context beyond annotations: the return format with status field and conditional fields, typical timing, and explicitly states 'Read-only and spends no quota', which aligns with readOnlyHint=true and destructiveHint=false annotations.
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 sentences, all essential: purpose, response format, polling guidance, and alternative for expired URL. Front-loaded with main purpose. No fluff.
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 one parameter, full schema coverage, good annotations, and no output schema, the description comprehensively covers its behavior, response shape, and relationship to sibling tools. Perfectly adequate.
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% with a single parameter 'job_id' described as 'The jobId render_async returned.' The description mentions jobId in return format but adds no new semantics beyond the schema. Baseline 3 is 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?
The description states 'Poll an asynchronous render job started by render_async', which is a specific verb (poll) and resource (render job). It clearly distinguishes from sibling tools like 'render_async' (starts job) and 'get_render' (gets fresh URL).
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 explicitly says when to use the tool (poll jobs started by render_async), provides polling frequency advice ('every few seconds rather than tight loop'), and names an alternative ('pass its render id to get_render for a fresh one') for expired URLs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replay everything recorded under one run_id — artifacts from attest_artifact and calls from record_agent_action — in order, with each record's link to its parent hash. Use it to answer 'what did this agent actually do, and in what sequence?' during an incident review, a handover, or an audit. Returns { run_id, chain_intact, records: [...] }, where chain_intact is the server's verdict on whether the parent-hash links are unbroken across the run. Read-only. Requires a Kamy API key.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | The run_id you passed to attest_artifact / record_agent_action. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, so the 'Read-only' line is redundant. However, the description adds valuable context beyond the annotations: results are ordered, chain_intact represents the server's verdict on hash-link integrity, and an API key is required. This is more depth than typical read-only tools.
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 sentences, each adding critical information: the action, the data sources, the use case, the return shape, the chain_intact meaning, read-only status, and auth requirement. Nothing is redundant or fluff; it is front-loaded with the core behavior.
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 lacking an output schema, the description explicitly returns { run_id, chain_intact, records: [...] } and explains chain_intact. It covers purpose, usage context, parameter origin, auth requirement, and read-only nature. For a single-parameter read-only tool with good annotations, this is fully sufficient.
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%, with run_id already described as 'The run_id you passed to attest_artifact / record_agent_action.' The description adds minimal new semantics—it reinforces that run_id is a single ID and ties it to prior calls, but this largely mirrors the schema. Baseline 3 is 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?
The description clearly states the tool replays all records under a run_id, specifically artifacts from attest_artifact and calls from record_agent_action, in order with parent-hash links. This distinguishes it from siblings like trace_record or trace_search by focusing on a single run's full provenance chain.
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 explicitly says to use this tool when you need to answer 'what did this agent actually do, and in what sequence?' during incident review, handover, or audit. It gives concrete use cases but does not mention when not to use it or name explicit alternatives, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one previously produced document by its render id, with a freshly signed download URL valid for the next hour. This is the recovery path for an expired link: the URL is minted at read time, so calling this again on an old render always yields a working download. Use list_renders first if you do not have the id. Returns { id, name, templateId, templateName, status, bytes, durationMs, url, createdAt }, where url is null when the render failed, has not finished yet, or its file has aged out of retention — check status before assuming a download exists. Read-only and spends no quota.
| Name | Required | Description | Default |
|---|---|---|---|
| render_id | Yes | Render id (UUID) as returned by render_pdf, render_async/get_job, or list_renders. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotated as readOnlyHint and destructiveHint false, the description adds significant behavioral detail: the URL is freshly signed and valid for 1 hour, calling again always yields a working download, URL is null under specific failure/retention conditions, and it spends no quota. No contradiction with annotations.
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 sentences, no redundancy. The main action and immediate benefit (fresh URL) are first, followed by usage guidance, return fields, and read-only note. Every sentence adds value.
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 fetch tool with one parameter and no output schema, the description fully explains the return structure, edge cases (null URL), idempotency, and quota impact. No missing information needed for an agent to use 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?
The input schema already describes render_id as a UUID with constraints. The description adds context by listing the source tools (render_pdf, render_async/get_job, list_renders) that produce the id, which helps the agent construct valid parameters. This is beyond the schema description.
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 uses the specific verb 'Fetch' and identifies the resource as 'previously produced document by its render id'. It distinguishes from siblings by advising to use list_renders first if the id is unknown, and implicitly differentiates from render_pdf (which produces) and get_render_pages (pages).
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 (recovery path for expired links, when you have the render id) and provides an alternative (list_renders if id not known). It does not explicitly exclude other scenarios like fetching pages, but the context is clear enough for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rasterise every page of an existing render to a PNG image and return one signed 1-hour URL per page, with pixel width and height. Use this when a page has to be looked at rather than read — thumbnails, previews, visual QA of a layout, or an image attachment — and use extract_from_render when you want the text. The render must already have status 'success'; a queued or failed one comes back as 409 RENDER_NOT_READY. Repeated calls overwrite the same page images, so it is safe to retry. Rasterisation costs no render quota. Returns { pages: [{ page, width, height, url }], count, dpi }.
| Name | Required | Description | Default |
|---|---|---|---|
| dpi | No | Raster resolution. Defaults to 150 (screen quality); 300 for print-quality thumbnails. Clamped to 72-300 server-side. | |
| render_id | Yes | Render id (UUID) as returned by render_pdf, render_async/get_job, or list_renders. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds valuable behavioral context beyond annotations: it states rasterisation costs no quota, repeated calls overwrite same images (safe to retry), and returns structure with pages, count, dpi. Annotations already indicate readOnly and non-destructive, but description enriches with concrete details and error condition.
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?
Two sentences, zero wasted words. Every phrase adds value: purpose, usage guidance, prerequisite, idempotency, cost, output format. Front-loaded with key action and result. Excellent structure.
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 explicitly documents the return format (pages array with page, width, height, url, count, dpi). Covers preconditions, error behavior, idempotency, and quota. Complete for a read-only tool with clear inputs and outputs.
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 both parameters thoroughly (e.g., defaults, clamping for dpi). The description does not repeat parameter details, which is appropriate given schema richness. No additional parameter semantics beyond what schema provides, hence baseline 3.
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?
Description clearly states the tool rasterizes every page of a render to PNG images with signed URLs, and explicitly distinguishes from extract_from_render for text extraction. The verb 'rasterise' and resource 'render' are specific and 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 tells when to use (thumbnails, previews, visual QA, image attachment) and when not to (use extract_from_render for text). Also specifies prerequisite that render must have status 'success' and warns about 409 error. No ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the authenticated download URL for a signature request's Certificate of Completion PDF — the process audit trail (invite → opened → consent → signed, with IP / user-agent) that legal teams expect. Only available after the request reaches a terminal state. Without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| signatureRequestId | Yes | ID of the signature_request to fetch the Certificate of Completion for. Must be in a terminal state (signed / declined / delegated / voided / expired); pending requests return 409. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context beyond annotations: the URL is authenticated, availability depends on terminal state, and the error path when no key is present. This is consistent with the annotations and enhances transparency.
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 concise, consisting of only two sentences plus a parenthetical. It front-loads the main purpose, then adds the audit trail context and usage constraints without any redundancy or wasted words.
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?
With no output schema, the description sufficiently explains the return value (authenticated download URL) and what the PDF contains. It also covers key usage constraints (terminal state, API key behavior). The parameter is fully documented in the schema, so the description is complete for this simple 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 coverage is 100%, with the signatureRequestId parameter fully described including the terminal-state requirement and 409 error. The description adds context about the certificate's purpose but does not provide additional parameter-level semantics beyond what the schema already documents.
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 verb 'Returns' and the specific resource 'authenticated download URL for a signature request's Certificate of Completion PDF'. It distinguishes itself from sibling tools by focusing on the audit trail content, making its purpose 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?
The description provides explicit guidance on when to use the tool ('Only available after the request reaches a terminal state') and notes the requirement for an API key. However, it does not name alternative tools for related actions (e.g., retrieving the signed document), so it lacks a full when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one signature request by id, with the detail list_signature_requests leaves out: the placed_fields layout, signed_at plus signed_ip and signed_user_agent, last_reminded_at, cc_emails, and envelope_id + recipient_order when it is part of an envelope. Use list_signature_requests to find an id and this to inspect it; use get_signature_certificate when what you actually want is the legal audit-trail PDF rather than the row. status is one of pending, waiting, signed, declined, delegated, voided or expired — waiting means a sequential envelope has not reached this signer yet, so nothing is wrong and no reminder is due. Read-only and spends no quota. Requires a Kamy API key with the signatures:read scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| signatureRequestId | Yes | ID returned by create_signature_request, bulk_signature_requests, or a list call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already mark readOnlyHint=true, the description adds substantial behavioral context: it is read-only and spends no quota, requires a specific API key scope, and explains error behavior (without a key, returns dashboard setup instructions). It also clarifies the nuanced 'waiting' status semantics for sequential envelopes. No contradiction with annotations.
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 concise yet information-dense: each sentence earns its place. It is front-loaded with the core action, then details additional fields, usage guidance, status enum explanation, and auth requirements, all in a compact, readable structure.
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 get-by-id tool, the description is complete: it covers the return fields, relationship to sibling tools, status values, auth requirements, and failure mode. No output schema exists, but the description sufficiently communicates the returned data elements, making the tool fully comprehensible.
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% and the schema description already explains the parameter's origin (returned by create_signature_request, bulk_signature_requests, or a list call). The description only says 'by id' without adding new meaning, so this dimension is adequately served by the schema. Baseline 3 is 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?
The description opens with a specific verb and resource ('Fetch one signature request by id'), clearly stating what the tool does. It distinguishes itself from siblings by enumerating the additional fields it returns (placed_fields, signed_at, etc.) and naming alternatives like list_signature_requests and get_signature_certificate, making the tool's unique role obvious.
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?
Provides explicit when-to-use guidance: 'Use list_signature_requests to find an id and this to inspect it' and 'use get_signature_certificate when what you actually want is the legal audit-trail PDF rather than the row.' Also explains the 'waiting' status meaning, preventing misinterpretation. This is a model example of usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one e-signature preset in full, including the placed_fields array and position that list_signature_templates omits. Use it to inspect or copy an existing field layout before applying it through create_signature_request's signatureTemplateId, or as the starting point for a preview_field_placement check against a new render. Read-only and spends no quota. Requires a Kamy API key with the signatures:read scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| signatureTemplateId | Yes | ID from list_signature_templates. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false. Description adds 'Read-only and spends no quota' and specifies auth scope, providing extra behavioral context beyond annotations.
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 sentences, each adding value. Front-loaded with purpose and key distinction. No 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?
Covers what the tool returns (placed_fields, position), usage scenarios, auth requirements, and quota behavior. Though no output schema, description sufficiently informs agent about expected output.
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% with schema description 'ID from list_signature_templates.' Description repeats exactly that. No additional param semantics added beyond schema, so baseline 3 is 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?
The description explicitly states it fetches a full e-signature preset including placed_fields and position, which list_signature_templates omits. This clearly distinguishes it from the sibling tool.
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?
Describes when to use: inspect/copy layout before create_signature_request or as starting point for preview_field_placement. Also mentions required scope. No explicit exclusions, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Everything needed to go from nothing to a rendered document in one call: the steps to create an API key in the dashboard, and — when you name a framework — the install command for the Kamy SDK, the environment variable it reads, and the client-setup snippet for that stack. Add a template slug and it also returns a ready-to-paste route handler that renders it. Every argument is optional and each one only adds a section, so calling this with no arguments is the right move when a user has no key yet, and calling it with framework + template is the right move when they are wiring the first endpoint. This replaces the separate install_sdk, generate_integration_code and get_api_key_instructions tools removed in 1.5.0. Pure text: it makes no API call, reads no account state, and needs no API key.
| Name | Required | Description | Default |
|---|---|---|---|
| template | No | Template slug (e.g. 'invoice') to also emit a ready-to-paste route handler that renders it. Requires `framework`. Call list_templates first if you do not know the slug. | |
| framework | No | Stack being integrated. Omit to get only the API-key steps; supply it to also get the install command, the environment variable, and the client-setup snippet. | |
| packageManager | No | Package manager for the install command. Default npm. Ignored for Python stacks. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description goes beyond by stating 'Pure text: it makes no API call, reads no account state, and needs no API key.' This explicitly confirms no side effects or dependencies, fully disclosing the tool's behavior. No contradiction with annotations.
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 a single, well-structured paragraph that front-loads the core value proposition and proceeds logically through parameters and usage guidance. Every sentence is informative with no redundancy or filler, and it wastes zero words.
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, the description clearly enumerates what the tool returns (API key steps, install command, environment variable, client-setup snippet, optional route handler). Given the tool's simplicity (no API calls, no side effects) and the full schema coverage, the description is completely adequate and leaves no gaps.
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 baseline is 3. However, the description adds significant value: it explains that each parameter is optional and 'each one only adds a section,' clarifies that packageManager is ignored for Python stacks, and elaborates on what framework adds (install command, environment variable, client-setup snippet). This surpasses the baseline by providing practical usage details beyond the schema.
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 that get_started provides everything from nothing to a rendered document in one call, specifying the steps, commands, and snippets it returns. It distinguishes itself from siblings by naming the replaced tools (install_sdk, generate_integration_code, get_api_key_instructions) and emphasizing this is a consolidated onboarding endpoint.
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 explicitly advises when to call with no arguments (when user has no key yet) and when to include framework + template (when wiring the first endpoint). It also notes that template requires framework, and to call list_templates first if the slug is unknown. This provides clear usage context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the JSON Schema (exact data shape) and a copy-pasteable sample payload for a Kamy system template by slug. Call this before render_pdf so you fill the right fields with the right types instead of guessing. No authentication required.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Template slug — e.g. 'invoice', 'receipt', 'uae-tax-invoice'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds value by disclosing 'No authentication required' and describing the return content (JSON Schema + sample payload), which enhances behavioral understanding beyond the annotations.
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 two sentences long, front-loaded with the main action, and every sentence earns its place ('Fetch...', 'Call this before render_pdf...', 'No authentication required'). No fluff 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?
Given the tool's simplicity (one parameter, no output schema), the description is complete: it states what is returned (JSON Schema and sample payload), why it should be used (to fill correct fields/types), and the authentication requirement. No additional context is needed.
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 input schema already provides 100% coverage for the single parameter 'slug' with a clear description and example. The tool description only repeats 'by slug' without adding additional semantic detail, so it does not go beyond the schema.
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 uses a specific verb 'Fetch' and clearly names the resource: 'the JSON Schema (exact data shape) and a copy-pasteable sample payload for a Kamy system template by slug.' It also distinguishes itself from siblings by positioning as a prerequisite to render_pdf, which is a distinct purpose.
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 explicitly states when to use it: 'Call this before render_pdf so you fill the right fields with the right types instead of guessing.' This provides clear context and names the related tool render_pdf, but it does not explicitly list when-not-to-use scenarios or mention alternative tools like list_templates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one template version snapshot in full — html, css, schema, createdBy, createdAt — exactly as it was frozen when that version was cut. Use list_template_versions first to find the number. Use this to inspect what a released version actually contained, or to recover content a later draft edit overwrote; it changes nothing on its own, so pair it with rollback_template when you want that version live again. Takes a template UUID or slug. Read-only and spends no quota. Requires a Kamy API key with the templates:read scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| version | Yes | Version number from list_template_versions. | |
| templateId | Yes | Template UUID or slug — every /v1/templates route resolves either. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds significant value by stating 'Read-only and spends no quota' and 'Requires a Kamy API key with the templates:read scope; without a key, returns dashboard setup instructions'. This provides authentication and quota behavior beyond what annotations offer. The description does not contradict any annotations.
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 a single focused paragraph of three sentences. The first sentence front-loads the core purpose and fields. Each subsequent sentence earns its place: the second explains how to prepare and when to use alternatives, and the third covers prerequisites and constraints. No wasted words.
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 the low complexity (2 required parameters, no enums, no nested objects, no output schema), the description is fully complete. It explains the tool's purpose, usage context, prerequisites (API key scope), constraints (read-only, no quota cost), and directs to sibling tools for related tasks. The annotations already cover safety, so no additional behavioral details are needed.
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% with descriptions for parameters, so baseline is 3. The description reinforces that templateId accepts a UUID or slug and that version comes from list_template_versions, but does not add syntax or format details beyond what the schema already provides. No value is added for enum or nested objects as none exist.
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 'Fetch one template version snapshot in full' and enumerates the fields included (html, css, schema, createdBy, createdAt). It explicitly distinguishes from the sibling tool `list_template_versions` by directing the agent to use that first to find the version number, and from `rollback_template` by stating this tool inspects content while the other makes a version live.
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 when-to-use advice: 'Use this to inspect what a released version actually contained, or to recover content a later draft edit overwrote'. It also gives explicit when-not: 'it changes nothing on its own, so pair it with rollback_template when you want that version live again'. This clearly differentiates the tool's role from the sibling `rollback_template`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a stored asset by its upload id: filename, contentType, sizeBytes, status, its kamy://asset/<id> reference, and a freshly signed downloadUrl valid for one hour once the bytes exist. Its main use is confirming an out-of-band transfer landed — upload_file returns uploaded:false when the file was too large to pass inline and you PUT it yourself — because this read reconciles a still-'pending' row against storage and flips it to 'uploaded' the first time it sees the object. Also the way to mint a fresh download link after an earlier signed URL expired. Read-only and spends no quota. Requires a Kamy API key with the uploads:read scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| uploadId | Yes | Upload UUID returned by upload_file. The bare UUID, not the kamy://asset/... ref. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contains a critical contradiction: it claims 'Read-only and spends no quota' (consistent with readOnlyHint=true) but then describes a side effect: 'reconciles a still-'pending' row against storage and flips it to 'uploaded' the first time it sees the object.' This is a state change, contradicting the annotation. Per rubric, score 1 for contradiction.
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 dense with useful information and front-loaded with the return fields. It efficiently covers use cases, requirements, and behavior. While it is somewhat long, every sentence serves a purpose, earning a 4 rather than a perfect 5.
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 the contradiction, the description covers all needed context: it lists return fields, explains the reconciliation behavior, mentions the signed URL's validity, states quota and scope requirements, and notes what happens without a key. For a one-parameter tool with no output schema, this is very complete.
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 baseline is 3. The description repeats the schema's hint about using the bare UUID but adds no new parameter semantics. The single parameter is well-documented in the schema; the description does not enhance it further.
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 purpose: 'Look up a stored asset by its upload id' and enumerates the specific fields returned. It distinguishes itself from sibling tools like upload_file by explaining its role in confirming out-of-band transfers, making it 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?
The description explicitly states when to use the tool: confirming an out-of-band transfer landed and minting a fresh download link. It provides context by referencing upload_file's behavior and notes the required API key scope ('uploads:read'), giving clear guidance on prerequisites and use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the documents this account has already produced, newest first. This is how you find a PDF made earlier — in a previous turn, by a schedule, or by another process — when you no longer hold its URL. Download URLs returned by the render tools are signed and expire after an hour, so a link from earlier in the conversation is probably dead; find the render here, then call get_render with its id to mint a fresh one. Returns { renders: [{ id, name, templateId, templateName, status, bytes, durationMs, cost, createdAt }], total, page, pageSize, hasMore, currency }. The name field is whatever label was passed at render time, which is the fastest way to identify the right document. Read-only and spends no quota.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. Defaults to 1 (the most recent renders). | |
| page_size | No | Rows per page, 1-100. Defaults to 20. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the description builds on that by explicitly stating 'Read-only and spends no quota' and explaining URL expiration behavior: 'Download URLs returned by the render tools are signed and expire after an hour.' This adds critical context beyond the annotations.
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 front-loaded with the primary purpose and includes a clear use case explanation. It is slightly longer than necessary (about 4 sentences), but each sentence adds unique value: purpose, use case, expiration behavior, return type, and identification guidance. No redundant statements.
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 that there is no output schema and the tool is simple (two optional parameters), the description fully documents the return format, pagination behavior, and authentication-related side effects (URL expiration). It covers everything needed for an agent to use the tool effectively without gaps.
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 baseline is 3. The description adds semantic value by explaining that pagination defaults to page 1 (most recent renders) and that page_size defaults to 20. However, it doesn't further enrich the parameter meanings beyond what the schema already provides, so a 4 is appropriate for slight contextual addition.
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 starts with 'List the documents this account has already produced, newest first,' which is a specific verb plus resource. It clearly distinguishes from siblings like get_render (which retrieves a single render) and extract_from_render (which processes a render).
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 explicitly tells when to use this tool: when you need to find a PDF whose URL has expired ('a link from earlier in the conversation is probably dead'). It identifies the alternative sibling (get_render) and explains the workflow: find the render here, then get a fresh URL with get_render. It also states that the `name` field is the fastest way to identify the document, aiding selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List this account's recurring render schedules, newest first, with the id needed to delete one. Use it to answer what is already automated before creating a duplicate, and to diagnose a schedule that is not producing documents: each row carries enabled, schedule, timezone, next_run_at, and last_run_at / last_run_status / last_run_error from the most recent firing — last_run_error is where a delivery or quota failure shows up. Returns { schedules, total, limit, offset }. Read-only and spends no quota.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows to return, 1-100. Defaults to 50. | |
| offset | No | Rows to skip. Defaults to 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, confirming no side effects. The description adds beyond that: it explicitly states 'Read-only and spends no quota', which adds useful behavioral context (quota consumption) beyond the annotations. It does not contradict annotations.
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 concise with no wasted words. It front-loads key info: what it lists, ordering, and primary use cases. Every sentence adds value, covering purpose, use cases, fields, return structure, and safety. Ideal length for a simple list tool.
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 the simple schema (2 optional params), no output schema, and strong annotations, the description covers purpose, return fields, usage scenarios, and safety comprehensively. The only gap is that it doesn't list all response fields explicitly, but the sample ('schedules, total, limit, offset') covers the structure well.
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% with explicit descriptions for 'limit' and 'offset' (defaults, min/max). The description adds high-level context about pagination (total, limit, offset in response) but no param-level details beyond what's in the schema. Baseline 3 is 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?
The description specifies that the tool lists recurring render schedules with details like 'enabled, schedule, timezone, next_run_at', and explicitly distinguishes its purpose from sibling tools like 'create_schedule' and 'delete_schedule'. The verb 'list schedules' combined with concrete fields makes the purpose clear and specific.
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 explicitly tells when to use this tool: 'to answer what is already automated before creating a duplicate' (avoiding duplicate creation) and 'to diagnose a schedule that is not producing documents' (troubleshooting). This provides clear context for choosing it over create_schedule, delete_schedule, or other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List signature requests created by the configured Kamy account, newest first. Without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Default 50. | |
| offset | No | Default 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and non-destructive, so the description adds value by specifying the "newest first" ordering and the special behavior of returning dashboard setup instructions when no key is present. This gives the agent awareness of an edge case beyond just a read operation.
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?
Two sentences, direct and information-dense. The main purpose is stated first, with a valuable caveat in the second sentence. No whitespace 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?
For a simple list tool with two optional parameters and clear annotations, the description covers the core function, ordering, and a critical edge case. It doesn't detail the response structure, but that is not fully required given no output schema and the simplicity of the expected result.
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?
Both parameters limit and offset are fully described in the schema with defaults and constraints, so the description doesn't need to add anything. The description provides no additional parameter context, matching the baseline for high schema coverage.
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 uses the specific verb "List" and identifies the resource as "signature requests" scoped to "configured Kamy account" with "newest first" ordering, clearly distinguishing it from sibling tools like list_templates or create_signature_request.
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 implies usage for listing signature requests but does not explicitly mention alternatives or exclusions, such as using list_templates for templates. The "without a key" note provides some contextual guidance but not comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List this account's reusable e-signature presets — saved field placements, default invite message, default link lifetime and CC list — newest first. These are signing presets, NOT the document catalog: list_templates is what render_pdf draws from. Rows here carry only id, name, description, expires_in and cc_emails; call get_signature_template for the placed_fields and position. Pass an id as create_signature_request's signatureTemplateId to apply a preset instead of re-specifying the layout every time. Returns { templates, total, limit, offset }. Read-only and spends no quota. Requires a Kamy API key with the signatures:read scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, 1–100. Default 50. | |
| offset | No | Rows to skip. Default 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond the annotations (readOnlyHint=true, destructiveHint=false) by explicitly stating 'Read-only and spends no quota.' It also discloses the pagination response format and authentication requirement. No contradictions with annotations.
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 fairly long but every sentence adds necessary information: purpose, sibling distinction, data fields, usage in other tools, return format, authentication, and resource cost. It is front-loaded with the main purpose. Could be slightly tighter but not wasteful.
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 the tool's complexity (pagination, sibling differentiation, downstream usage), the description is complete. It covers purpose, scope, authentication, quota, output shape, and how to use the results. No output schema exists, but the return structure is described explicitly, so the agent has all necessary context.
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% with descriptions for limit and offset. The description adds context by stating the response includes 'limit' and 'offset' (part of the pagination structure), which helps users understand the parameters' role. It also mentions 'newest first' ordering, which is an implicit default behavior not captured in the schema.
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 verb and resource: 'List this account's reusable e-signature presets'. It distinguishes from the sibling tool 'list_templates' by explicitly stating that those are document catalogs used by render_pdf, while these are signing presets. It also specifies the data returned (id, name, description, expires_in, cc_emails) and the ordering (newest first).
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 versus alternatives: it contrasts with list_templates for document catalog, suggests get_signature_template for detailed fields, and explains how to use the id in create_signature_request. It also states the required scope (signatures:read) and behavior without a key, making usage conditions clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Kamy's public system PDF templates. No authentication required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: it specifies that the list covers only 'public system' templates and explicitly notes 'No authentication required', which goes beyond what annotations provide. It does not contradict the annotations.
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 two short sentences, front-loaded with the essential action and resource. Every word earns its place, and there is no redundancy or 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?
For a parameterless list tool with no output schema and annotations already covering safety, the description is complete: it tells what is listed, the scope, and the authentication requirement. No further information is needed for an agent to invoke this tool 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 tool has zero parameters, and the schema coverage is trivially 100%. Per the guidelines, a baseline of 4 applies for no-parameter tools. The description does not need to explain parameters, and it does not add any parameter-related noise.
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 action ('List'), the resource ('Kamy's public system PDF templates'), and the scope ('public'). This distinguishes it from sibling tools like get_template_schema or list_signature_requests, which target different resources or actions.
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 clear context by specifying the exact set of templates (public system PDF templates) and notes that no authentication is required. It does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to determine when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a template's immutable version snapshots, newest first, as { id, version, createdAt }. This is where the version number that publish_template and rollback_template take comes from. Bodies are deliberately not included — call get_template_version when you need one snapshot's html, css and schema. Works on system and public templates as well as your own, by UUID or slug. Read-only and spends no quota. Requires a Kamy API key with the templates:read scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| templateId | Yes | Template UUID or slug — every /v1/templates route resolves either. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and non-destructive, and the description reinforces this with 'Read-only' while adding new context: 'spends no quota', requires 'templates:read' scope, and behavior without a key. It also discloses that bodies are deliberately omitted. No contradiction; adds meaningful behavioral detail beyond annotations.
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 sentences, each conveying distinct useful information: output format, relationship to other tools, what is excluded, and access/auth notes. No wasted words, front-loaded with the primary action.
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 list operation with one parameter and no output schema, the description covers output shape, excluded data, how to obtain full snapshots, applicable templates, auth requirements, and quota impact. This is complete for an agent to select and invoke the tool 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% and already explains templateId as 'Template UUID or slug'. The description adds no new parameter semantics, reinforcing the same info. Since the schema fully documents the parameter, baseline 3 is 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?
The description states a specific action ('List a template's immutable version snapshots'), specifies the output shape ({ id, version, createdAt }), and differentiates from sibling tools like get_template_version and publish_template/rollback_template. It is clearly not a tautology and conveys the exact purpose.
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: to obtain version numbers for publish_template and rollback_template. Also gives an alternative (get_template_version for bodies) and scope of applicability (system, public, own templates by UUID or slug). This is exemplary usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the webhook endpoints registered on this account, with the id needed to test one. Each row carries url, events, enabled, and lastDeliveryAt / lastStatus from the most recent delivery — lastStatus is the HTTP code the caller's own server returned, so this is where a silently broken endpoint shows up as a 4xx or 5xx. Signing secrets are never returned here; they are shown only once, by create_webhook. Read-only and spends no quota.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool is read-only and spends no quota, aligning with annotations. It goes beyond by explaining that signing secrets are never returned and that lastStatus shows the HTTP code from the caller's server, indicating where a silently broken endpoint appears. This provides valuable behavioral context not captured in annotations.
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 three sentences, front-loading the main purpose. It is clear and concise, but could be slightly tighter by removing some detail about lastStatus (though that detail is useful). Still, it earns its keep without excessive verbosity.
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?
With no output schema, the description partially describes return values (fields like id, url, events, enabled, lastDeliveryAt, lastStatus). It covers the main aspects of what the tool returns. It does not mention pagination, error cases, or the exact structure, but given the simplicity of listing all webhooks, this is adequate. A bit more on the response format would improve completeness.
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 are no parameters, so the description does not need to add meaning. The schema coverage is 100%, and the description does not mention parameters, which is appropriate. Baseline 4 is justified as the description adds no parameter information, but none is needed.
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 verb 'List' and the resource 'webhook endpoints' on the account. It specifies the purpose: to get the id needed to test one, and distinguishes from the sibling create_webhook by noting that signing secrets are not returned here. The mention of fields (url, events, enabled, lastDeliveryAt, lastStatus) adds specificity.
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 implies when to use: to list webhooks and get ids for testing. It explicitly contrasts with create_webhook for secrets. It also states it is read-only and spends no quota, which guides safe usage. However, it does not explicitly mention when to use the sibling test_webhook, though it implies the id is for testing. Lacks a direct 'when not to use' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Concatenate 2–20 existing renders into a single new PDF, in exactly the order the ids are given. Both the inputs and the output are Kamy render ids, so this is the composition step after several render_pdf / convert_document / edit_pdf calls — it cannot merge arbitrary URLs or raw bytes, and every id must belong to this account and point at a completed render or the whole call fails. The source renders are left untouched. Returns a new render { id, url, bytes, durationMs }. Billed as one additional render. Requires a Kamy API key with the render scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Label for the merged render, e.g. 'Q3 statement bundle'. | |
| renderIds | Yes | 2–20 render UUIDs owned by this account, in the page order you want. Any id that isn't yours, or whose render didn't complete, fails the whole call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-readOnly, non-destructive behavior, which the description affirms ('source renders are left untouched'). The description goes beyond annotations by detailing billing implications ('Billed as one additional render'), authentication requirements ('Kamy API key with `render` scope'), and failure behavior (atomic failure on any bad id). No contradictions with annotations.
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?
Every sentence earns its place: operation, ordering, preconditions, limitations, side effects, billing, auth. The description is front-loaded with the core action, two sentences long, and no filler. Highly efficient.
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 the tool's moderate complexity (2 params, no output schema), the description is fully sufficient. It covers input constraints, failure modes, billing, auth, and relationship to siblings. No gaps remain for an agent to make an incorrect invocation.
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 adds value by reinforcing the ordering constraint ('in exactly the order the ids are given') and the atomic failure condition, which the schema's JSON description implies but doesn't state as clearly. The `name` parameter is well-contextualized as a label in the description's example ('Q3 statement bundle'). A 4 is warranted because the description meaningfully enriches the schema's semantics.
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 uses a specific verb ('Concatenate') and resource ('existing renders into a single new PDF'), clearly states the input range (2–20), and distinguishes this tool from siblings like 'split_pdf' and 'edit_pdf'. The context of being a composition step after other render calls is explicit.
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 specifies exactly when to use this tool ('composition step after several render_pdf / convert_document / edit_pdf calls'), what it cannot do ('cannot merge arbitrary URLs or raw bytes'), and clear failure conditions ('every id must belong to this account and point at a completed render or the whole call fails'). This contrasts well with sibling tools that might handle raw input or single-document operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cryptographically sign an existing render with PAdES when a Kamy API key is configured. Without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Optional /Sig dictionary Reason — surfaced in Acrobat's signature panel. ASCII-coerced server-side. | |
| location | No | Optional /Sig dictionary Location. | |
| renderId | Yes | Render UUID returned by render_pdf or any /v1/render call. The PDF will be sealed with a Kamy-issued X.509 leaf certificate. | |
| signerName | No | Override the signer display name. Defaults to the account's full_name. | |
| signerEmail | No | Override the signer email. Defaults to the account's email. | |
| withTimestamp | No | When false, skip the RFC 3161 timestamp call (PAdES-B-B instead of B-T). Default: true. | |
| withRevocationInfo | No | When false, skip embedding the Kamy CA CRL into the PKCS#7 SignedData (PAdES-B-T instead of B-LT). Online verifiers can still fetch the CRL via the Distribution Point on the leaf cert. Default: true. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, providing minimal safety signals. The description adds valuable non-obvious context: the cryptographic nature (PAdES), the API key requirement, and the conditional return of setup instructions. However, it does not disclose other behaviors like idempotency, side effects on the render, or failure modes beyond the missing key.
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?
Two sentences, front-loaded with the primary action and the key condition. No filler words; every phrase adds information. The conditional 'Without a key' is an efficient way to describe the no-key scenario.
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 tool has 7 parameters and no output schema. The description covers the prerequisite and fallback output, but does not mention what a successful signing returns (e.g., a signed PDF, a status object, or a render ID). It also omits any warnings about irreversibility or the need for the render to be in a valid state. Given the parameter richness is handled by the schema, this gap prevents a higher score.
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 each parameter has a clear description in the schema itself. The tool description adds no parameter-specific meaning beyond what the schema documents, but that is acceptable because the schema carries the full burden. A baseline of 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 uses a specific verb ('sign') and resource ('existing render') with the method ('PAdES'), clearly distinguishing it from sibling tools like render_pdf (creates renders) and verify_pdf_signature (verifies). The phrase 'existing render' reinforces it is a follow-on action.
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 explicitly states the prerequisite ('when a Kamy API key is configured') and the fallback behavior when the key is missing. It implies usage on existing renders rather than new ones, which distinguishes it from render_pdf, but it does not explicitly name alternative tools or when not to use it (e.g., for verification).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a placedFields layout against a real render's page geometry before anything is sent: no signature request is created, no email goes out, and no signature quota is spent. It accepts exactly what create_signature_request accepts — all seven field types, options, and anchor-positioned fields — so anything that previews clean will send. Returns each page's true width and height, so a sender UI can draw a preview at the right aspect ratio, plus per field valid / issues / the resolved coordinates the request would actually be stored with, after sourcePage scaling and anchor substitution. Issues are PAGE_OUT_OF_RANGE, OFF_PAGE_RIGHT, OFF_PAGE_TOP, DUPLICATE_NAME, ANCHOR_NOT_FOUND (the anchor text is not on that page, so the field falls back to the raw x/y) and OPTIONS_REQUIRED. None of these make create_signature_request fail — that is the point of checking here, because a field that lands off the page is accepted and emailed. The source render must have status 'success'; if its PDF has aged out of storage the call returns 410 and the fix is to re-render. Read-only. Requires a Kamy API key with the signatures:read scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| renderId | Yes | Render UUID whose real page sizes the fields are checked against. | |
| placedFields | Yes | Up to 100 fields to validate. Exactly the shape create_signature_request takes — same seven types, same `anchor` and `options` support — so a layout that previews clean is a layout that sends. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, destructiveHint), the description discloses key behaviors: no signature request is created, no email is sent, no quota is spent. It details what the tool returns (page dimensions, per-field validity, issues list with specific issue types) and what happens when the render PDF has aged out (410 error). The anchor-fallback behavior (silent fallback to raw x/y if anchor text not found) is explicitly described, adding substantial behavioral context beyond annotations.
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 front-loaded with the essential purpose in the first sentence. Every subsequent sentence adds relevant detail: what the tool does not do, what it returns, edge cases (410, anchor behavior), prerequisites, and auth requirements. No filler or redundancy – each piece earns its place. The structure is logical and easy to parse.
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 the tool's moderate complexity (2 params, no output schema, but annotations present), the description covers all key aspects: purpose, return values (page dimensions, issues list), prerequisites (render status), error handling (410), behavioral nuances (anchor fallback), and authorization. The lack of output schema is fully compensated by the detailed description of what the tool returns. It leaves no critical gaps for an agent to misinterpret.
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 adds significant value by contextualizing the parameters: 'It accepts exactly what create_signature_request accepts — all seven field types, options, and anchor-positioned fields' and 'so anything that prewiews clean will send.' It also explains how the parameters relate to the validation flow and what the returned issues mean. This goes beyond mere parameter repetition, earning a 4.
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 opens with a clear verb-resource pair: 'Check a placedFields layout against a real render's page geometry before anything is sent.' It explicitly states what the tool does (preview/validate) and which resource it operates on (placedFields layout + render page geometry). It distinguishes itself from create_signature_request by noting that no signature request, email, or quota is spent during preview.
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: before sending a signature request ('anything that prewiews clean will send'). It explains that issues like ANCHOR_NOT_FOUND or OFF_PAGE are not failures in create_signature_request but are caught here. It also states a prerequisite ('The source render must have status success') and how to handle a 410 error (re-render). Authorization requirements (Kamy API key with signatures:read scope) are also specified, giving clear usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Make a template version live for rendering. Called with no version, it snapshots the current draft into a new version and points published_version at it — this is how you ship an edit made with update_template. Called with an existing version, it republishes that earlier snapshot and leaves the draft alone. Reach for rollback_template instead when you are reverting a bad release: only that tool offers the concurrency fence and the option to restore the draft as well. Takes a template UUID or slug, same as every other /v1/templates route. Returns { templateId, publishedVersion, publishedVersionId, latestVersion, publishedAt }. Requires a Kamy API key with the templates:write scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| version | No | Omit to snapshot the current draft into a new version and publish that. Supply an existing version number to republish a known-good earlier snapshot, leaving the draft untouched. | |
| templateId | Yes | Template UUID or slug — every /v1/templates route resolves either. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are present (readOnlyHint=false, destructiveHint=false) but minimal. The description adds significant behavioral context: the two mutation modes, the return shape, and the auth requirement. No contradiction with annotations. The description fully explains the tool's behavior beyond what annotations provide.
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 five sentences, front-loaded with the main action, and each sentence serves a distinct purpose: main action, two modes, alternative tool, parameter format, return shape, and auth requirement. No redundant or filler content.
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 two parameters and no output schema, the description covers the return shape explicitly, auth requirements, and alternative tool. It lacks error handling details (e.g., what happens if the template doesn't exist or version is invalid), but given the typical complexity of such tools, it is mostly complete.
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% and the schema already describes both parameters well. The description adds value by explaining the two modes of the `version` parameter in natural language, linking it to the `update_template` workflow, and noting that `templateId` accepts a UUID or slug. The extra context is helpful but not extensive beyond the schema.
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 verb 'publish' and object 'template version', and distinguishes two modes: snapshotting the current draft or republishing an existing version. It also explicitly differentiates from the sibling tool rollback_template, leaving no ambiguity about what the tool does.
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 gives explicit when-to-use guidance: 'Called with no version, it snapshots the current draft... this is how you ship an edit made with update_template' and 'Reach for rollback_template instead when you are reverting a bad release'. It also mentions that without the proper API key, it returns dashboard setup instructions, effectively guiding the agent on prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append one signed tool_call -> tool_result pair to a tamper-evident ledger. Call it after any consequential tool invocation — a payment, an outbound email, a write into a customer system — so there is a hash-chained record of what the agent asked for and what came back, signed at write time. Pass a stable run_id to keep an entire agent run in one chain, and parent_sha256 to link records explicitly; read the result back with get_provenance_chain. Returns { record_id, content_sha256, signature, recorded_at, verify_url }. Requires a Kamy API key.
| Name | Required | Description | Default |
|---|---|---|---|
| tool | Yes | Name of the tool that was invoked. | |
| run_id | No | Your identifier for this agent run. Reuse it across records to build one chain. | |
| server | Yes | Identifier of the MCP server (or tool provider) the call went to, e.g. 'kamy'. | |
| status | No | Outcome of the call. Defaults to ok. | |
| tool_call | No | The request you sent — typically the arguments object, verbatim. | |
| latency_ms | No | Wall-clock duration of the call. | |
| tool_result | No | The result you received back, verbatim. | |
| parent_sha256 | No | content_sha256 of the previous record in this run, to link the chain explicitly. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only, not destructive, and not open-world. The description adds value by disclosing the tool's write behavior (signed hash-chained record), authentication requirement ('Requires a Kamy API key'), and the return format details. However, it doesn't explicitly state if the tool is idempotent or how errors are handled.
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 sentences, each earning its place: first defines the core action, second gives usage context, third explains key parameters and return value, fourth states authentication. No filler or repetition.
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 an 8-parameter, 2-required tool with full schema coverage and no output schema, the description is complete. It covers what the tool does, when to use it, how to use it (key parameters), what it returns, and its authentication needs. The return format is described sufficiently without an 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?
Schema description coverage is 100%, so the baseline is 3. The description adds context for run_id (using across records) and parent_sha256 (to link explicit chain), but it doesn't add meaning beyond the schema descriptions for other parameters. The enum for status is already clear in the schema.
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 uses a specific verb ('append') and resource ('tool_call -> tool_result pair to a tamper-evident ledger'), clearly distinguishing the tool from its siblings. It explicitly states the tool is for recording signed pairs after consequential tool invocations, which is unique among sibling tools like ask_kamy or trace_record.
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 gives explicit when-to-call guidance: 'Call it after any consequential tool invocation — a payment, an outbound email, a write into a customer system'. It also provides a clear when-not-to-call hint by implication (only for consequential actions) and references a sibling, get_provenance_chain, for reading results back.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resend the signature invitation email. Pass signatureRequestId to nudge one signer, or envelopeId to nudge every currently-pending recipient of an envelope — supply exactly one; there is no separate envelope-reminder tool. This sends real email to third parties. Each recipient is capped at one reminder per hour: the single-request form returns 429 REMIND_TOO_SOON with a Retry-After header, while the envelope form silently skips capped recipients and reports skipped_reason per row, so read the per-recipient results rather than assuming everyone was mailed. Only pending recipients are reminded — signed, voided and expired requests return 409, and sequential recipients still in 'waiting' are skipped because it is not their turn. A manual nudge also counts toward the three-reminder auto-cadence cap. Requires a Kamy API key with the signatures:write scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| envelopeId | No | Nudge every currently-pending recipient of this envelope. Supply exactly one of signatureRequestId or envelopeId. | |
| signatureRequestId | No | Nudge this one signer. Supply exactly one of signatureRequestId or envelopeId. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (non-readonly, open world, non-destructive), the description explains that this sends real email to third parties, discloses the one-per-hour cap and the silent skipping behavior for envelope-level nudges, and warns that a manual nudge counts toward the auto-cadence cap. Also mentions auth scope requirements. No contradictions with annotations.
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 relatively compact for the amount of information it covers (5 sentences). It is front-loaded with the core action. However, it packs a lot of edge cases and behavior into a single paragraph, which could be segmented for clarity.
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 2 simple parameters, no output schema, and critical real-world consequences (email sending, rate limits, silent skipping), the description covers all necessary behavioral aspects: who gets reminded, who gets skipped, error conditions, rate limit handling, and auth requirements. It leaves no obvious gaps.
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 baseline is 3. The description adds value by explaining the exclusivity constraint ('supply exactly one') and the behavioral difference between the two parameters (single signer vs. all pending). However, the schema already provides a description for each parameter, so the added value is moderate.
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 starts with 'Resend the signature invitation email' which is a specific verb+resource combination. It clearly distinguishes itself by noting that pass a single parameter (envelopeId or signatureRequestId) to nudge either a single signer or an entire envelope, and explicitly states there is no separate envelope-reminder tool.
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?
Provides explicit when-to-use guidance: pass signatureRequestId for one signer, envelopeId for all pending recipients. Also details exclusions: only pending recipients are reminded, signed/voided/expired return 409, sequential recipients still waiting are skipped. Mentions rate limits and how to handle them (read per-recipient results).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Queue one PDF render and return immediately with { jobId, status: 'queued' } instead of waiting for the document. Choose this over render_pdf when blocking is not acceptable — a heavy template, a large data set, or a turn where you have other work to do — and poll get_job with the returned jobId until status is 'completed' (the finished render, including its download URL, arrives on the job) or 'failed'. Choose render_pdf when a single document is small enough that waiting a few seconds is fine and you want the URL in one call, and render_batch when you have many documents to make at once. Same template, data and page options as render_pdf, and the same one render from the monthly quota — the quota is checked when the job is accepted, so an over-quota call fails here with 402 rather than silently queueing.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Data used to populate the template. | |
| name | No | Your own label for this document. Echoed back on the job result and stored on the render, so list_renders can be grepped by it later. | |
| pdf_a | No | Convert the output to a PDF/A archival conformance level. | |
| format | No | Paper size. Defaults to a4. | |
| margin | No | CSS lengths, e.g. { top: '20mm', bottom: '20mm' }. | |
| metadata | No | PDF document properties written into the file's metadata dictionary. | |
| template | Yes | Template slug (e.g. 'invoice') or template UUID. Same values render_pdf accepts. | |
| watermark | No | Draws your own diagonal watermark over every page. Unrelated to the free-plan Kamy watermark, which is applied regardless — see get_account.watermarkPolicy. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the async return pattern, quota check at acceptance (with 402 error), and that the finished render arrives on the job with download URL. Adds context beyond annotations (readOnlyHint=false, destructiveHint=false) by explaining the polling mechanism and shared options with render_pdf.
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 a single paragraph of about 100 words, well-organized: first the core behavior, then usage guidance, then quota and polling. Every sentence adds value, though it could be slightly more compact by combining some ideas.
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 the complexity (async, polling, quota, no output schema), the description covers the return format, polling protocol, quota check, and options shared with render_pdf. It does not provide the full structure of the job result object, but that is partially covered by get_job's description. Overall, it is sufficiently complete for an agent to use 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 baseline is 3. The description adds value by noting that name is echoed back, watermark is unrelated to Kamy watermark, and that parameters are the same as render_pdf. This provides agent-level understanding beyond the schema.
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?
Clearly states the verb (queue/return) and resource (PDF render) with the async behavior ('return immediately with { jobId, status: 'queued' }'). Distinguishes from siblings by naming render_pdf and render_batch, making the unique purpose unmistakable.
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 prescribes when to choose this tool ('when blocking is not acceptable'), when to choose alternatives (render_pdf for small documents, render_batch for many documents), and how to use it (poll get_job). Also covers quota behavior and error handling, leaving no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render up to 100 documents in a single blocking call, each from its own template, HTML or URL, and get every result back in one response. Choose this over calling render_pdf in a loop whenever you have more than a couple of documents — it is one round trip, one quota reservation and one rate-limit charge. It does block: items render sequentially inside a 300-second budget, so expect to wait, and reach for render_async instead when you cannot. Returns { results: [...] } in request order, where each entry is either a finished render or an { error: { code, message } } — a partial batch is normal and successful items are still yours. The whole batch's quota is reserved up front, so a batch that would cross the monthly quota is rejected in full with 402 and nothing is rendered; call get_account first if you are near the limit. Items that would overrun the time budget come back as SERVICE_UNAVAILABLE having been neither rendered nor billed — retry just those in a smaller batch.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | 1-100 documents to render, in order. Results come back in this same order. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations are minimal (readOnlyHint=false, etc.), so the description carries the full burden. It richly discloses behavioral traits: the tool blocks and renders sequentially within a 300-second budget, partial batches are normal with per-item errors, quota is reserved upfront leading to full rejection on quota exceedance, and time-budget overruns yield SERVICE_UNAVAILABLE without billing. This far exceeds what annotations provide.
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 approximately 150 words across 6 sentences, which is slightly long but each sentence adds unique value. It is front-loaded with the core purpose and usage guidance, then layers in behavioral details. Could be slightly more concise by removing the example response structure, but overall earns its length.
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 the tool's complexity (batch processing, partial failures, quota, timeout), the description is remarkably complete. There is no output schema, so the description compensates by explaining the return format and error semantics. It covers all major dimensions: what it does, when to use vs. alternatives, behavioral traits, and how errors/quota/timing work. No gaps identified.
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. However, the description adds meaningful context about the batch-level behavior (e.g., partial errors, quota reservation, time-budget overrun handling) that enriches understanding beyond parameter-level descriptions. It explains the response structure and error semantics, which is not in the schema. The slight deduction is because it doesn't elaborate on each parameter individually, but the aggregate value is significant.
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 purpose: 'Render up to 100 documents in a single blocking call, each from its own template, HTML or URL, and get every result back in one response.' It uses a specific verb ('render') and resource ('batch of PDFs'), and implicitly distinguishes itself from siblings like render_pdf and render_async.
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 explicitly tells when to use this tool over alternatives: 'Choose this over calling render_pdf in a loop whenever you have more than a couple of documents' and 'reach for render_async instead when you cannot [block].' It also provides when-not-to-use guidance (when blocking is unacceptable). This is a textbook example of usage guidelines.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render an editable Word (.docx) document from a Kamy template and data. Takes the same { template, data } payload as render_pdf but produces a different container — reach for it when the recipient has to EDIT the document (legal redlines, Word-based intake, corporate templates) rather than receive a fixed artifact. Only five slugs have a Word implementation — invoice, receipt, quote, contract, agreement — and any other template is rejected with a validation error; use render_pdf for those. Returns { id, url, bytes, durationMs, format: 'docx' }, where url is a signed download link valid for one hour and id is a normal render id. Counts one render against the monthly quota. Requires a Kamy API key with the render scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | Template data, identical in shape to the render_pdf payload for the same slug — call get_template_schema first to get the exact fields. | |
| name | No | Label stored on the render row so the document is identifiable in the dashboard. | |
| template | Yes | Which built-in document to build. These five are the only slugs with a Word implementation; custom templates and other system templates are PDF-only (use render_pdf). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint false and destructiveHint false, so the description's disclosure of non-destructive behavior (render, counts quota, requires API key) adds marginal value. However, it goes beyond annotations by specifying the signed URL expiry (one hour), return format details, quota counting, and authentication requirements. One point off because the annotation 'openWorldHint: false' is not contradicted, but the description doesn't explicitly address whether the tool has side effects beyond rendering.
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?
Earned: the three-sentence description is tightly packed with essential information—purpose, sibling differentiation, slug limitations, return structure, quota, auth requirements. Every sentence adds unique value; no filler or repetition.
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 the tool has three parameters (1 required), 100% schema coverage, and annotations covering safety, the description is nearly complete. It explains the return format, quota, auth, and template restrictions. One point off because there is no output schema to assist with return-field types, and the description omits the expected HTTP response codes or potential errors (beyond validation).
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 all three parameters (template, data, name) with their constraints and basics. The description adds meaning by mapping the payload shape to render_pdf and advising to use get_template_schema for exact fields, but does not add syntax details beyond what the schema provides. Baseline 3 is 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?
The description clearly states the tool renders an editable .docx document from a Kamy template and data, using a specific verb ('Render') and resource ('Word document'). It distinguishes itself from the sibling render_pdf by noting the different output container and use case, and it explicitly lists the five supported slugs (invoice, receipt, quote, contract, agreement), leaving no 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 provides explicit guidance on when to use this tool ('recipient has to EDIT the document') versus when not to ('use render_pdf for those' rejected templates). It names the sibling render_pdf directly as an alternative, and explains the limitation to five slugs with a rejection fallback, leaving no guesswork for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compile a Kamy template — or raw Handlebars source you pass inline — against a data payload and get the rendered HTML string back. No browser runs, no PDF is produced and no file is stored, so this is the tool for piping a template into a transactional email provider, or for inspecting the markup before committing to render_pdf. Use render_pdf instead whenever the output has to be a paginated, printable artifact. Supply exactly one of template or html. Returns { format: 'html', html, bytes }. Paid-tier system templates are refused on the free plan. Counts one render against the monthly quota, since the compile step is the shared cost. Requires a Kamy API key with the render scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | Values substituted into the template's Handlebars expressions. | |
| html | No | Raw Handlebars/HTML source to compile instead of a stored template. Supply exactly one of template or html. | |
| template | No | Template slug or UUID — a Kamy system template or one of your own. Supply exactly one of template or html. | |
| direction | No | Force the document's lang/dir attributes for RTL/bidi mail clients. 'auto' (default) leaves the template's own <html lang> untouched. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already give readOnlyHint=false (mutation), destructiveHint=false, so description adds meaningful context: returns specific format object, counts against monthly quota, requires api key with 'render' scope, and mentions refusal of paid-tier templates on free plan. No contradictions with annotations.
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?
Description is front-loaded with core compile action, then scoping constraints, then alternatives, then output, then edge cases. Each sentence serves a purpose; no fluff. Could be slightly tighter by moving quota info later, but still efficient for length.
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 4 parameters with 100% schema coverage, no output schema needed due to clear return format described, and sibling tools providing context, the description covers purpose, usage, constraints, auth, quotas, and output shape completely. No gaps remain.
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 baseline is 3. The description adds value by explaining the template vs html mutual exclusivity, but does not add new details about direction or data param beyond what schema already states. Adequate but does not substantially extend schema information.
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?
Description specifies verb 'compile' and resource 'Kamy template or raw Handlebars source', clearly distinguishes the output (HTML string) from sibling tools like render_pdf by explicitly stating 'no PDF is produced and no file is stored'. It also differentiates from render_docx, render_pptx, render_xlsx by focusing on HTML output.
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 tells when to use this tool (piping into transactional email, inspecting markup) and when not to ('use render_pdf instead whenever the output has to be a paginated, printable artifact'). Also gives precise condition for 'Supplies exactly one of template or html' with constraint details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a PDF from a Kamy template and data, and wait for it. This is the default document tool: it blocks until the file exists and hands back { id, url, bytes, durationMs, templateId, createdAt } in one call, where url is a signed download link valid for one hour and id is the render id every later tool takes. Reach for render_async instead when waiting is not acceptable, and render_batch when several documents are wanted at once. Call get_template_schema first if you are unsure what fields the template expects. Counts one render against the monthly quota — get_account tells you what is left before this fails with 402. Requires a Kamy API key with the render scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Data to populate the template | |
| format | No | a4 | |
| template | Yes | Template slug (e.g., 'invoice') or template UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint false and readOnlyHint false; the description adds critical behavioral details beyond annotations: it blocks until file exists, returns a signed download URL valid for one hour, counts against a monthly quota (402 on failure), requires 'render' scope API key, and returns setup instructions without a key. This is excellent coverage of side effects, auth, and error cases.
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 a single paragraph of 5 sentences, front-loaded with the core action and return value. Every sentence adds value (siblings, prerequisites, quotas, auth). Slightly dense but not verbose; could potentially split into bullet points for readability, but still efficient.
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 3 parameters, no output schema, and moderate complexity (blocking, quota, auth), the description is thoroughly complete. It explains return format, timeouts, error conditions, prerequisites, and alternatives. No obvious gaps remain for an agent to invoke the tool 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 67% (two of three parameters have descriptions). The description adds context for the template parameter (slug or UUID), but does not elaborate on the data parameter beyond what the schema says. The format parameter's enum values (a4, letter) are self-explanatory. The description adds marginal value for parameters but is adequate given coverage.
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 verb 'Render' and the resource 'PDF from a Kamy template and data,' and distinguishes it from siblings by noting that this is the default blocking tool. It specifies the exact return object and key fields like id, url, bytes, etc., making the purpose 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?
The description provides explicit guidance: use this tool when waiting is acceptable, reach for render_async when waiting is not acceptable, render_batch for multiple documents, and call get_template_schema first if unsure about template fields. It also mentions quota implications and API key requirements, offering comprehensive when-to-use and when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build a PowerPoint (.pptx) deck from a slide spec: an ordered array of slides, each tagged with one of five fixed layouts (title, bullets, two-column, table, quote). This is NOT a template renderer like render_pdf / render_docx — there is no template slug and no free-form layout, so content has to be shaped into those five. It also converts nothing; use convert_document to turn a file you already have into a PDF. Returns a stored render { id, url, bytes, durationMs, format } where url is a signed download link valid for one hour; the deck is a .pptx, so feed the id to convert_document if the next step needs a PDF (merge_pdfs, split_pdf and the signature tools take PDFs only). Counts one render against the monthly quota. Requires a Kamy API key with the render scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| theme | No | ||
| title | No | Deck title — used as document metadata and as the returned filename stem. | |
| format | No | WIDE = 16:9 (default), STANDARD = 4:3. | WIDE |
| slides | Yes | Ordered slides. Each carries a `layout` discriminator: 'title', 'bullets', 'two-column', 'table' or 'quote'. There is no free-form layout — content that doesn't fit one of the five should be reshaped into bullets or a table. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond annotations, which only state readOnlyHint=false and destructiveHint=false. It discloses that the return format is a .pptx with a signed download link valid for one hour, that it counts against a monthly quota, and that a specific API key scope ('render') is required. There are no contradictions with annotations (annotation_contradiction=false).
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 front-loaded with the core action and key constraint. It efficiently covers purpose, boundaries, and post-processing guidance in a compact paragraph. While it is informative, a slight restructuring could improve readability (e.g., separating use-case guidance from technical details), and there is minor redundancy (e.g., layout types mentioned twice).
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 the complexity of nested slide objects and the lack of an output schema, the description adequately explains the return structure (id, url, bytes, durationMs, format) and links to next steps (conversion). It also covers quota and auth requirements. It could be improved by explicitly noting whether the output bytes include the full file or serve as metadata, and by confirming that the .pptx extension is always used, but overall it is thorough.
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 high (75%), and the description reinforces the meaning of the `slides` parameter by detailing the five fixed layouts and explicitly stating 'no free-form layout.' It adds clarity beyond the schema by explaining that content must be shaped into these five types. However, it does not add specific details about the `theme` or `format` parameters beyond what the schema provides, which keeps it from a 5.
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 uses a specific verb ('Build') and clearly defines the resource ('PowerPoint (.pptx) deck'). It distinguishes itself from sibling tools like render_pdf, render_docx, and convert_document by stating it is NOT a template renderer and does not accept a template slug, and that convert_document should be used for file conversion.
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 explicitly tells when to use this tool (to create a deck from a slide spec with five fixed layouts) and when NOT to use it (not a template renderer, not a converter). It provides alternatives: convert_document for file conversion, and notes that merge_pdfs, split_pdf, and signature tools require PDFs, so the output should be converted first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build an Excel (.xlsx) workbook from a sheet spec: columns with keys, row objects keyed to those columns, optional Excel number formats and a formula-aware total row (bare 'SUM' / 'AVG' / 'COUNT' / 'MIN' / 'MAX' expands into a real formula over the column's data range). Choose this over render_pdf when the recipient will sort, filter or recompute the numbers, and over render_docx when the content is tabular rather than prose. Returns a stored render { id, url, bytes, durationMs, format } where url is a signed download link valid for one hour; the workbook is a .xlsx, so feed the id to convert_document if the next step needs a PDF. Header rows are always bold on a tinted fill — there is no flag for it. Counts one render against the monthly quota. Requires a Kamy API key with the render scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Workbook title — document metadata and the returned filename stem. | |
| sheets | Yes | One or more sheets, in tab order. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint=false, destructiveHint=false), so the description carries the burden. It discloses: authentication requirement (Kamy API key with `render` scope), quota counting, signed URL expiry (1 hour), and the formula-expansion behavior for totalRow. It also notes that header rows are always bold/tinted with no flag. Missing: rate limits, error handling, or what happens if quota is exceeded. Still strong, but not exhaustive.
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?
Two compact paragraphs. The first sentence immediately states the core purpose. Subsequent sentences add details, usage guidance, return format, and behavioral notes in logical order. Every sentence earns its place; no fluff or repetition.
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, the description fully describes the return object (id, url, bytes, durationMs, format) and the signed link validity. It covers authentication, quota, and formula behavior. The sibling set is large, but the description clearly differentiates from the two most similar tools. No gaps in guidance for a typical agent invoking this 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 coverage is 100% with good descriptions, but the description adds significant value: it explains the formula-expansion mechanism ('bare 'SUM' / 'AVG' / 'COUNT' / 'MIN' / 'MAX' expands into a real formula'), the behavior of strings starting with '=', and the literal fallback. It also clarifies that header styling is automatic. This goes beyond the schema's basic property descriptions.
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 opens with a clear, specific verb ('Build an Excel (.xlsx) workbook') and defines the resource as a sheet spec with columns, rows, number formats, and a formula-aware total row. It distinguishes itself from siblings render_pdf and render_docx, explaining exactly when each alternative is appropriate.
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 this tool over render_pdf ('when the recipient will sort, filter or recompute the numbers') and over render_docx ('when the content is tabular rather than prose'). Also provides guidance on chaining: 'feed the id to convert_document if the next step needs a PDF.' No ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revert a template after a bad release: repoints published_version at the version you name, so every subsequent render immediately serves that snapshot again. Prefer this over publish_template's version argument whenever you are reverting, because only this tool takes expectedPublishedVersion — an optimistic fence that rejects with 409 VERSION_CONFLICT if someone moved the pointer since you read it — and only this tool can restore the working draft too. restoreDraft: true overwrites the draft html/css/schema with that version's content, auto-snapshotting the existing draft into a fresh version first so unsaved work is recoverable; it defaults to false. Destructive: it changes what production renders, and there is no undo beyond rolling forward again. Takes a template UUID or slug. Requires a Kamy API key with the templates:write scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| version | Yes | The known-good version to make live again. Get it from list_template_versions. | |
| templateId | Yes | Template UUID or slug — every /v1/templates route resolves either. | |
| restoreDraft | No | When true, also overwrite the working draft (html/css/schema) with that version's content. The current draft is auto-snapshotted into a new version first, unless it is already byte-identical. Defaults to false, which leaves in-flight edits alone. | |
| expectedPublishedVersion | No | Optimistic fence: the published_version you believe is live (0 if never published). The call is rejected with 409 VERSION_CONFLICT if someone moved the pointer in the meantime. Pass it whenever you read the state in an earlier step. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, but the description adds meaningful context: 'no undo beyond rolling forward again', the draft snapshotting behavior, and the 409 conflict mechanism. It clearly discloses what gets changed and the safety net for drafts.
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?
Somewhat long, but each sentence adds functional or safety information. Front-loaded with the core purpose, then alternative guidance, then param details. No redundant filler; minor length is justified by complexity.
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?
Covers all key aspects: what it does, when to use, destructive impact, auth, parameter nuances, and concurrency safety. Despite no output schema, the description gives enough context to select and invoke correctly. The inclusion of a fallback behavior (dashboard instructions) is a nice touch.
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 covers all parameters at 100%, but description adds value by explaining the practical semantics of restoreDraft (auto-snapshotting, byte-identical check) and expectedPublishedVersion (optimistic fence). It clarifies edge-case behavior not spelled out in the schema.
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?
Clear verb ('revert') and resource ('template') with explicit effect: 'repoints published_version at the version you name'. Distinguishes itself from publish_template by explaining the unique rollback behavior and draft restoration.
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: 'Prefer this over publish_template's version argument whenever you are reverting', and reasons why (optimistic fence and draft restore). Also mentions auth requirement and fallback behavior without a key.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Heuristic pattern scan of MCP tool description text for prompt-injection tells — instructions addressed at the reading model, data-exfiltration hints, attempts to override your system prompt or hide content. Run it on descriptions from third-party MCP servers before you act on what they say. Returns risk 'low' | 'medium' | 'high' and the matched findings with excerpts. This is a heuristic aid, NOT a security boundary: a 'low' verdict is not evidence that a tool is safe, and an injection phrased to avoid the patterns will score low. Do not treat any result here as clearance to trust an untrusted tool — keep your own judgement and human review in the loop. Read-only: it analyses only the text you pass in and fetches nothing. Requires a Kamy API key.
| Name | Required | Description | Default |
|---|---|---|---|
| tools | No | Several tools at once — e.g. the entries of a `tools/list` result. Supply description, tools, or both. | |
| description | No | A single tool description to scan. Supply description, tools, or both. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds significant behavioral context: it notes that the tool is a 'heuristic aid', not a security boundary, and explains its limitations ('a 'low' verdict is not evidence that a tool is safe, and an injection phrased to avoid the patterns will score low'). It also states it is read-only, analyzes only the passed text, and requires a Kamy API key. This goes well beyond the annotations, providing essential transparency about the tool's fallibility and operational constraints.
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 a single, well-structured paragraph of about 100 words. It front-loads the purpose and key differentiators, then covers usage guidelines and behavioral notes. Every sentence adds distinct information: purpose, use case, output type, limitations, and authentication requirement. No redundancy or 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?
Given that the tool has 2 parameters, no output schema, and no nested objects, the description is richly complete: it explains what the tool does, how to use it, what to expect as output (risk levels and excerpts), its limitations, and the auth requirement. This is more than sufficient for a tool of this complexity, especially with the complementary annotations and schema coverage.
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 description adds context for both parameters: it explains that 'description' is for a single tool description to scan, while 'tools' is for multiple assets (e.g., from a tools/list result), and that either supply is acceptable. The description also clarifies that the tool expects description text specifically for prompt injection scanning, not arbitrary input. Despite the schema already documenting the fields, the description elaborates on the use cases and input types, adding value.
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 that the tool scans MCP tool description text for prompt-injection tells, specifying the verb 'scan', the resource ('tool description'), and the scope ('instructions addressed at the reading model, data-exfiltration hints, attempts to override your system prompt or hide content'). It also explains the output (risk level and findings), fully differentiating it from sibling tools like 'ask_kamy', 'attest_artifact', or 'verify_mcp_server', which have different purposes.
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 explicitly states when to use the tool ('Run it on descriptions from third-party MCP servers before you act on what they say'), what it should not be treated as ('a security boundary', not 'clearance to trust an untrusted tool'), and what the model should do instead ('keep your own judgement and human review in the loop'). This provides comprehensive guidance, including exclusions and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract page ranges from one existing render into separate new PDFs — the inverse of merge_pdfs. Each range you pass produces its own render, returned in the same order, so one call can both halve a contract and peel off single pages. Omit a range's to to run to the end of the document; a range starting past the last page fails the entire call. The source render is left untouched. Returns { renders: [...], count }, each entry a normal render object usable with merge_pdfs, edit_pdf or the signature tools. Requires a Kamy API key with the render scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| ranges | Yes | 1–50 page ranges; each produces one output render, returned in this order. A range that starts past the last page fails the whole call. | |
| renderId | Yes | UUID of the completed render to split. Must belong to this account. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already indicate non-destructive and non-read-only behavior, the description adds substantial detail: the source render is left untouched, error handling for out-of-range pages, the return format {renders: [...], count}, and integration with sibling tools. This goes well beyond the annotations.
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 three sentences, each earning its place: definition and inverse, usage examples, and behavioral/auth/return details. No redundant or filler content.
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 the tool has 2 parameters (100% schema coverage), no output schema, and moderate complexity with nested arrays, the description compensates fully by specifying return format, error atomicity, auth requirements, and compatibility with sibling tools. No significant gaps remain.
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?
With 100% schema coverage, the baseline is 3. The description adds value by explaining that omitting a range's 'to' runs to the end, that a range starting past the last page fails the entire call, and that outputs are returned in the same order as ranges. These nuances are not fully captured in the schema.
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 extracts page ranges from a render into new PDFs and explicitly identifies it as the inverse of merge_pdfs, providing a specific verb and resource with direct sibling differentiation.
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 contrasts the tool with merge_pdfs and gives concrete usage examples (halving a contract, peeling off single pages). It does not explicitly state when not to use it or list all alternatives like edit_pdf, but the context is clear and helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a real test.ping event to a registered webhook endpoint — an actual outbound HTTP POST to whatever URL the user configured, signed like a genuine delivery. Use it to prove an endpoint is reachable and that signature verification works before relying on it. Delivery is dispatched in the background, so the { message: 'Test ping dispatched' } you get back means accepted for sending, not that the endpoint answered: wait a few seconds and call list_webhooks to read lastStatus and lastDeliveryAt for the real outcome. The ping is delivered regardless of which events the endpoint subscribes to.
| Name | Required | Description | Default |
|---|---|---|---|
| webhook_id | Yes | Webhook endpoint id (UUID) from create_webhook or list_webhooks. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by disclosing that delivery is dispatched in the background, the response means accepted for sending (not delivered), and how to check the real outcome via list_webhooks. It also notes the ping is delivered regardless of subscriptions. This is rich behavioral context consistent with the annotations.
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 a bit long but every sentence carries important information: the action, the purpose, the background dispatch behavior, and the subscription note. It is front-loaded with the core action and remains efficiently structured.
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 single-parameter tool with good annotations, the description fully covers the operational context: what is sent, how to interpret the response, and how to verify the outcome. It even describes the response shape despite no output schema, making it complete.
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% and the single parameter webhook_id is already described in the schema as 'Webhook endpoint id (UUID) from create_webhook or list_webhooks.' The description adds no additional parameter-level meaning, so the baseline of 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 clearly states the tool sends a real test.ping event via an outbound HTTP POST to a registered webhook endpoint, distinguishing it from sibling tools like create_webhook or list_webhooks. The action is specific and the resource is well-defined.
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 explicitly says to use the tool to prove an endpoint is reachable and signature verification works before relying on it, providing clear when-to-use context. It does not explicitly name when-not-to-use alternatives, but it does point to list_webhooks for follow-up verification, which is helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record one LLM call — prompt, output, provider, model, tokens, latency — into Kamy Trace, a signed retention ledger. Each record is hashed and signed at write time, so it can be produced later without the 'you could have edited this' objection. Reach for it when model calls need a reviewable history: regulated workflows, customer-facing generations, anything you may have to explain months later. Set status 'flagged' with status_detail on calls a human should revisit. Returns { id, content_sha256, signature, recorded_at, verify_url }. Requires a Kamy API key with the trace:record scope; each call consumes monthly Trace quota.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Up to 20 free-form labels. trace_search can filter on any one of them. | |
| model | Yes | Model identifier exactly as the provider reports it, e.g. 'claude-sonnet-4-6'. | |
| output | No | The model's response, verbatim. Any JSON value. | |
| prompt | No | The prompt / request you sent, verbatim. Any JSON value (string, array, object). | |
| status | No | Outcome. 'flagged' marks a call you want a human to review later. Defaults to 'ok'. | |
| feature | No | Product area the call belongs to, e.g. 'support_reply'. Filterable in trace_search. | |
| provider | Yes | Which model vendor served the call. Use 'custom' for anything self-hosted. | |
| latency_ms | No | Wall-clock duration of the call. | |
| input_tokens | No | Prompt tokens billed. | |
| output_tokens | No | Completion tokens billed. | |
| status_detail | No | Why the call was flagged or failed. Free text. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=false, destructiveHint=false) indicate a write operation that is not destructive. The description adds substantial behavioral context: records are hashed and signed at write time for tamper evidence, returns a specific structure ({ id, content_sha256, signature, recorded_at, verify_url }), requires a Kamy API key with trace:record scope, and consumes monthly Trace quota. There is no contradiction with annotations.
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 approximately 7 sentences, each serving a distinct purpose: stating the core function, explaining hashing/signing, providing usage context, noting status options, listing return fields, and specifying auth/quota. There is no redundancy or extraneous information. It is front-loaded with the primary purpose.
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 11 parameters (2 required) and no output schema, the description covers the return value structure, authentication requirements, and quota consumption. It does not address error handling or rate limits, but it provides sufficient context for an agent to invoke the tool appropriately. The missing output schema is partially compensated by the description of the return object.
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 mentions several parameters (prompt, output, provider, model, tokens, latency) but does not add significant new information beyond what the schema already provides for each parameter. The schema already includes descriptions for tags, feature, status, etc. The description adds no extra parameter-level semantics.
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 action ('Record one LLM call') and the specific resource components (prompt, output, provider, model, tokens, latency) into Kamy Trace. It distinguishes itself from sibling tools like trace_search, which searches records, and other tools that handle different tasks (e.g., attest_artifact, record_agent_action). The purpose is specific and 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?
The description provides explicit usage guidance: 'Reach for it when model calls need a reviewable history: regulated workflows, customer-facing generations, anything you may have to explain months later.' It also mentions using 'flagged' status for human review. However, it does not explicitly state when not to use it or compare to alternative tools like record_agent_action, which could record similar events. The context is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write up to 100 Kamy Trace records in one call. Reach for this over trace_record whenever you have more than a couple of buffered LLM calls to persist — it is one auth, one quota check and one round trip instead of N. Each element takes exactly the shape trace_record takes. The whole batch is counted against the monthly Trace quota up front, so a batch that would cross the plan cap is rejected in full with 402 and nothing is stored; split it or upgrade rather than retrying. Returns { records: [{ id, content_sha256, signature, recorded_at, verify_url }] } in input order. Requires a Kamy API key with the trace:record scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| records | Yes | 1–100 records, each exactly the shape trace_record takes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which are minimal), the description discloses key behaviors: the batch is counted against quota upfront, a rejected batch returns 402 and stores nothing, and the return format is provided. No contradictions with annotations.
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 concise (about 5 sentences) and front-loaded with purpose, then usage, then behavioral details, then return format, then auth. Every sentence adds value with no 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?
Given the tool's complexity (batch operation, quota, auth, return format), the description covers all essential aspects: capacity, when to use, quota behavior, identical shape to trace_record, return structure, and auth requirements. No output schema exists, but the return format is explicitly described.
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 adds that each element takes the same shape as trace_record, which is helpful but not necessary since the schema fully defines each field. No additional parameter semantics beyond the schema.
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 writes up to 100 Kamy Trace records in one call, with a specific verb ('Write') and resource. It explicitly distinguishes from the sibling tool trace_record by recommending this tool when there are more than a couple of buffered calls, which sets it apart effectively.
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?
Provides explicit guidance on when to use this tool over trace_record ('more than a couple of buffered LLM calls'), explains the quota rejection behavior and how to handle it ('split it or upgrade'), and mentions the required API key scope. This gives the agent clear decision-making criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query this account's Kamy Trace records, newest first, filtered by feature, status, provider, tag, or time window. Returns record metadata — model, tokens, latency, status, content hash, recorded_at — plus next_cursor for paging; it does not return the stored prompt and output bodies. Use it to answer questions like 'how many flagged calls last week?' or to locate a specific record's id before opening it in the dashboard. Read-only. Requires a Kamy API key with the trace:read scope.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Return records whose tags array contains this tag. | |
| limit | No | Page size, 1-100. Default 25. | |
| since | No | ISO-8601 timestamp, inclusive lower bound. | |
| until | No | ISO-8601 timestamp, exclusive upper bound. | |
| cursor | No | Pass the `next_cursor` from the previous response to fetch the next page. | |
| status | No | Exact-match filter on outcome. | |
| feature | No | Exact-match filter on the feature label. | |
| provider | No | Exact-match filter on provider. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description's read-only mention adds little beyond them. However, it adds valuable context about auth requirements (requires Kamy API key with trace:read scope) and pagination (next_cursor, no return of prompt bodies), which annotations don't cover. The description aligns with annotations.
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 concise: four sentences, each adding value. It front-loads the core function (query traces with filters, newest first), then details return data and exclusions, provides usage examples, and ends with access requirements. No wasted words.
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 the 8 parameters with 100% schema coverage but no output schema, the description adequately describes output fields and pagination. It lacks details on default ordering (newest first is mentioned), but covers key behavioral aspects. The tool is a filtered list query with good annotations, so completeness is solid.
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 lists filter dimensions (feature, status, provider, tag, time window) and mentions returned fields (model, tokens, status, etc.), but doesn't add significant meaning beyond what the schema already provides for each parameter. It provides a useful high-level summary but doesn't deepen parameter understanding.
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 tool queries Kamy Trace records with specific filters (feature, status, provider, tag, time window) and returns metadata. It clearly distinguishes itself from sibling tools like trace_record (which likely returns a single record) and other sibling tools that deal with documents, signatures, or attestations.
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 explicitly says when to use it (e.g., 'how many flagged calls last week?' or locating a record ID before opening the dashboard) and implies when not to (it does not return stored prompt/output bodies). It also states it is read-only and requires a specific API key scope, providing clear context for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit an existing custom template's DRAFT — name, html, css, schema, tags, visibility — addressed by UUID or slug. Only the fields you pass are changed. Crucially, this does not change what renders once the template has been published even once: while published_version is set, render_pdf serves that frozen snapshot and your edits stay invisible until publish_template moves the pointer, so an edit that appears to do nothing usually needs a publish. System templates, and templates belonging to another account, return 403. Requires a Kamy API key with the templates:write scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| css | No | Replaces the draft CSS entirely. | |
| html | No | Replaces the draft HTML entirely. | |
| name | No | ||
| tags | No | ||
| schema | No | Replaces the draft JSON Schema entirely. | |
| isPublic | No | ||
| template | Yes | Template UUID or slug. This route accepts either. | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, destructiveHint=false, and the description goes far beyond that, disclosing the crucial freeze/publish behavior, 403 conditions, and auth requirements. This provides essential behavioral context not inferred from annotations alone.
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 dense but efficient, front-loading the core purpose and then adding behavioral nuance. It is slightly long due to necessary detail, but every sentence earns its place with no fluff.
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 8 parameters, 50% schema coverage, no output schema, and no annotations beyond basic flags, the description covers the tool's behavior well. It explains the draft/publish lifecycle and error conditions. Minor gap: no mention of return value or side effects (e.g., no destruction, but destructiveHint=false already covers that).
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 50% (4 of 8 parameters have descriptions). The description adds value by summarizing the updatable fields and stating 'Only the fields you pass are changed,' but does not explain the template field format beyond what the schema says, and some params like isPublic and tags lack description in both schema and description.
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 uses a specific verb ('Edit') and resource ('custom template's DRAFT'), listing the editable fields and addressing mechanism. It clearly distinguishes from siblings like publish_template and create_template by noting that edits remain invisible until published.
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 explicitly states when to use this tool ('Edit an existing custom template's DRAFT') and what it does not do ('does not change what renders once published'), with a clear alternative: 'needs a publish.' It also covers prerequisites and restrictions (system templates, other accounts, API key scope).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store an image, font or PDF in the account's asset bucket and get back a kamy://asset/<id> reference you can drop anywhere inside a render_pdf / render_html data payload — Kamy swaps it for a fresh signed URL at render time. That reference is the point of this tool: it is how a logo, signature image or custom font gets into a template without hosting it yourself. Pass contentBase64 and this server performs the upload for you, returning { id, assetRef, bytes, uploaded: true }. Omit contentBase64 for files too big to pass through a tool call and you get the raw slot instead — { uploadUrl, uploadMethod, uploadHeaders, expiresAt, uploaded: false } — then PUT the bytes yourself within 15 minutes. Inline uploads are capped at 5 MB here; the API itself allows 100 MB via that URL. Only the listed MIME types are accepted. Requires a Kamy API key with the uploads:write scope; without a key, returns dashboard setup instructions.
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | Name to store the asset under. Characters outside [A-Za-z0-9._-] are replaced with '_'. | |
| sizeBytes | No | Declared size in bytes. Computed automatically when contentBase64 is supplied. Max 100 MB. | |
| contentType | Yes | MIME type. The API rejects anything outside this list. | |
| contentBase64 | No | Base64 bytes to upload. When supplied, this server PUTs them to the pre-signed URL and the asset is immediately usable. Omit for files too large to pass through a tool call — you then get uploadUrl back and PUT the bytes yourself within 15 minutes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint: false, destructiveHint: false) indicate a write operation but not destructive. The description adds rich behavioral context: two upload modes, 15-minute expiry for deferred uploads, size caps, MIME restrictions, and authentication requirement. No contradiction with annotations.
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 a single coherent paragraph that front-loads the purpose, then systematically covers the two modes, limits, and requirements. Every sentence provides essential information without redundancy. It is appropriately sized for the tool's complexity.
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 the tool's complexity (two modes, auth, size caps, MIME list, return values), the description covers all critical aspects. It even describes both return formats and what happens when the API key is missing. No output schema exists, but the description fully compensates by detailing the response structure.
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 input schema covers all parameters with descriptions (100% coverage), so baseline is 3. The description adds significant behavioral value by explaining the dual-mode behavior of contentBase64 and the filename replacement rule, which goes beyond the schema descriptions. However, it does not add entirely new parameter meaning for all params.
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 explicitly states the tool stores an image, font, or PDF into an asset bucket and returns a kamy://asset/<id> reference. It clearly differentiates from sibling tools (e.g., render_pdf) by explaining that the reference is used inside render payloads.
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 two clear usage paths: inline upload with contentBase64 or deferred upload by omitting it. It specifies MIME type restrictions, file size limits (5 MB inline, 100 MB via URL), and API key scope requirement. It also implies when to use this tool (to get assets into templates) versus alternatives (the render tools themselves).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dry-run a render payload against a template's schema WITHOUT producing a PDF or using quota. Returns per-field self-healing errors (expected type, value received, allowed values, an example) so you can fix the data before render_pdf. Requires a Kamy API key.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | The data payload to validate against the template schema. | |
| template | Yes | Template slug (e.g. 'invoice') or template UUID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly, non-destructive), the description adds valuable behavioral details: it does not generate a PDF or use quota, requires a Kamy API key, and returns self-healing per-field errors including expected type, value received, allowed values, and an example. This exceeds the annotation baseline and provides significant operational context.
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 concise, front-loads the primary action, and every clause adds value—mentioning the dry-run nature, the return error format, the parallel to render_pdf, and the auth requirement. Nothing is redundant or 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 the tool's moderate complexity, the description covers the purpose, usage timing, return behavior, and auth requirement. Since there is no output schema, the description sufficiently explains what the tool returns (self-healing errors). It leaves minimal gaps for an agent to misuse the 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%, with both parameters already described ('data' as the payload and 'template' as slug or UUID). The description does not add extra meaning beyond the schema, so it stays at the baseline of 3.
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 validates a payload against a template schema, with a specific verb ('Dry-run'), and distinguishes itself from render_pdf by explicitly noting it does NOT produce a PDF or consume quota. This makes the purpose unambiguous and differentiates it from sibling tools.
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 gives clear context by saying it lets you 'fix the data before render_pdf,' implying it should be used prior to rendering. However, it does not explicitly mention when not to use it or name alternative tools like get_template_schema, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask Kamy whether a SHA-256 digest has an attestation on record — the tool that actually returns a verdict. Takes a digest, not a file: if what you hold is a PDF, run verify_pdf_signature over the bytes first and pass the sha256 it gives you. A match returns { verified: true, artifact_type, recorded_at, signature, public_key }. A false result means no attestation exists for those exact bytes, which happens both when content was altered after attestation and when it was simply never attested; it does not by itself identify tampering or a culprit. Public surface — like the extract_document verify URL, no API key is required, so a recipient can confirm an artifact independently of whoever sent it.
| Name | Required | Description | Default |
|---|---|---|---|
| hash | Yes | SHA-256 of the artifact you want to check, as hex. Hash the bytes you actually hold — if they were modified after attestation, the digest won't match any record and `verified` comes back false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only and non-destructive. The description adds substantial behavioral context: the exact return fields (verified, artifact_type, etc.), interpretation of false results, and the public nature of the endpoint. No contradiction with annotations.
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 concise at about 5 sentences, front-loading the core purpose. Every sentence adds meaningful information: purpose, input format, workflow, result interpretation, and public access. No unnecessary words or repetition.
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 the tool's simplicity (single parameter, no output schema), the description is remarkably complete. It covers input preprocessing, output fields, result semantics, and access context. The sibling tool verify_pdf_signature is referenced for the correct workflow. No major gaps.
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% with a clear description of the hash parameter. The description adds value by explaining that it takes a digest (not a file) and providing preprocessing guidance for PDFs. This extra context goes beyond the schema's own description.
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 purpose: 'Ask Kamy whether a SHA-256 digest has an attestation on record' using a specific verb-resource combination. It distinguishes itself from siblings by explicitly contrasting with verify_pdf_signature and noting that it returns a verdict, unlike ask_kamy which is a general Q&A tool.
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: if you have a PDF, run verify_pdf_signature first and pass the resulting SHA-256. It explains what a false result means and that the tool is public, requiring no API key. It does not explicitly list alternatives or when to use ask_kamy instead, but the context is sufficient for correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detect when an MCP server changes its tool manifest after you adopted it — the 'rug pull' case, where a server you already trusted silently rewrites a tool's description or input schema. Pass server_url and Kamy fetches that third-party server's manifest itself, or pass manifest when you already hold it (local or private servers). Returns status 'new' (first fingerprint for this account — nothing to compare against yet), 'unchanged', or 'mutated', plus a per-tool changes list with previous and current hashes. 'unchanged' means only that it matches what Kamy recorded previously; it is not a judgement that the server is trustworthy, and a first-ever 'new' result establishes a baseline rather than clearing anything. Requires a Kamy API key.
| Name | Required | Description | Default |
|---|---|---|---|
| manifest | No | A tool manifest you already hold — the `tools/list` result, or an object with a `tools` array. Use this when the server isn't reachable from Kamy (local stdio server, private network). Supply either server_url or manifest. | |
| server_url | No | URL of the MCP server to fingerprint. Kamy fetches its tool manifest server-side. Supply either server_url or manifest. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, openWorldHint=true), the description discloses that the tool records fingerprints ('first fingerprint for this account'), explains the meaning of each status, and explicitly warns that 'unchanged' is not a trust judgement. It also states the API key requirement, adding transparency about auth needs.
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 compact yet dense, covering purpose, parameter selection, return statuses, caveats, and auth in about five sentences. No filler or redundancy; each sentence contributes essential 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?
For a tool with no output schema and an external-fetch+state-recording behavior, the description fully covers the return format, semantics, and prerequisites. It even explains first-run behavior and the non-judgemental nature of 'unchanged', leaving no major gaps.
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 both parameters, so the baseline is 3. The description adds value by explaining the selection logic: 'Pass server_url and Kamy fetches... or pass manifest when you already hold it (local or private servers)'—this provides practical guidance beyond the schema's 'Supply either' note.
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 opens with a specific verb+resource: 'Detect when an MCP server changes its tool manifest after you adopted it'. It clearly distinguishes this from sibling verification tools (e.g., verify_pdf_signature, verify_attestation) by focusing on manifest mutation.
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 gives clear context for when to use it (after adopting a server, to check for 'rug pull' manifest changes) and explains the two input modes (server_url for Kamy to fetch, manifest for local/private servers). It doesn't explicitly name alternatives, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn PDF bytes you are holding into their SHA-256 digest and the matching kamy.dev/verify/{sha256} page URL. Purely local: the MCP Worker hashes the base64 in memory, makes no Kamy API call, stores nothing and forwards nothing, so it works with no key and never leaves a trace. Note it returns no verdict — it does not tell you whether the document is genuine, signed, or on record anywhere. It is the first half of a check: take the sha256 it returns and pass it to verify_attestation for the actual yes/no, or hand a person the verify_url to open. Use this whenever you have the file itself; use verify_attestation directly when someone has already given you a digest.
| Name | Required | Description | Default |
|---|---|---|---|
| pdfBase64 | Yes | Base64-encoded PDF bytes. The MCP Worker hashes the file in-memory and does not store or forward it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses critical behavioral traits beyond annotations: purely local operation, no Kamy API call, no storage or forwarding, no key required, never leaves a trace. Also clarifies that no verdict is returned. Annotations (readOnlyHint, destructiveHint) are consistent with this description.
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 sentences, each adding value: core purpose, local nature, output limitations, usage guidance. No filler, information front-loaded. Every sentence earns its place.
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 fully explains what the tool returns (sha256 digest and verify URL) and what it does not (verdict). For a single-parameter, read-only tool, this is complete. Agent has all information needed to use the tool correctly and chain it with verify_attestation.
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% and the schema description already explains the pdfBase64 parameter clearly. The description adds behavioral context (in-memory hashing, no storage) but does not significantly expand parameter semantics beyond what is in the schema. Baseline 3 is 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?
The description uses specific verbs ('hash', 'build') and resources ('PDF bytes', 'SHA-256 digest', 'verify URL'), clearly distinguishing the tool from siblings like verify_attestation. It states exactly what the tool does and what it does not do.
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 explains when to use this tool ('whenever you have the file itself') and when to use the alternative verify_attestation ('when someone has already given you a digest'). Provides clear sequential guidance for the verification workflow.
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. Dates show when Glama detected each change.
edit_pdf3 fields changedInput schema / properties / operations / descriptionPrevious value: -"1–200 operations applied in the order given. 'fill_field' writes into an AcroForm widget; 'stamp_text' draws text at an absolute position; 'redact' paints an opaque rectangle over the region — it hides content visually but does NOT delete the underlying bytes, and the response carries a REDACT_VISUAL_ONLY warning for every redact op. Do not use it to remove secrets or personal data from a document you are about to hand out."New value: +"1–200 operations applied in the order given. 'fill_field' writes into an AcroForm widget; 'stamp_text' draws text at an absolute position; 'cover' paints an opaque rectangle over the region — it hides content visually but does NOT delete the underlying bytes, and the response carries a COVER_VISUAL_ONLY warning for every cover op. Anyone can still copy the text out from under the box. It is NOT redaction: never use it to hide secrets or personal data in a document you are about to hand out, and do not describe the result as redacted. There is no redaction operation — 'op: redact' is rejected with REDACTION_NOT_SUPPORTED. To remove sensitive data, regenerate the document without it."Input schema / properties / operations / items / anyOfPrevious value: -[
- {
- "additionalProperties": false,
- "properties": {
- "field": {
- "description": "AcroForm field name.",
- "maxLength": 200,
- "minLength": 1,
- "type": "string"
- },
- "op": {
- "const": "fill_field",
- "type": "string"
- },
- "value": {
- "anyOf": [
- {
- "maxLength": 2000,
- "type": "string"
- },
- {
- "type": "boolean"
- }
- ],
- "description": "Text value, or a boolean for checkbox widgets."
- }
- },
- "required": [
- "op",
- "field",
- "value"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "color": {
- "description": "6-digit hex colour, e.g. '#101014'.",
- "pattern": "^#[0-9a-fA-F]{6}$",
- "type": "string"
- },
- "fontSize": {
- "maximum": 300,
- "minimum": 1,
- "type": "number"
- },
- "op": {
- "const": "stamp_text",
- "type": "string"
- },
- "page": {
- "description": "1-based page number.",
- "maximum": 500,
- "minimum": 1,
- "type": "integer"
- },
- "text": {
- "maxLength": 2000,
- "minLength": 1,
- "type": "string"
- },
- "x": {
- "description": "X in PDF points from the left edge.",
- "maximum": 10000,
- "minimum": 0,
- "type": "number"
- },
- "y": {
- "description": "Y in PDF points from the BOTTOM edge.",
- "maximum": 10000,
- "minimum": 0,
- "type": "number"
- }
- },
- "required": [
- "op",
- "page",
- "x",
- "y",
- "text"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "color": {
- "$ref": "#/properties/operations/items/anyOf/1/properties/color",
- "description": "Fill colour of the box. Defaults to black."
- },
- "h": {
- "description": "Rectangle height in points.",
- "maximum": 10000,
- "minimum": 1,
- "type": "number"
- },
- "op": {
- "const": "redact",
- "type": "string"
- },
- "page": {
- "description": "1-based page number.",
- "maximum": 500,
- "minimum": 1,
- "type": "integer"
- },
- "w": {
- "description": "Rectangle width in points.",
- "maximum": 10000,
- "minimum": 1,
- "type": "number"
- },
- "x": {
- "description": "X in PDF points from the left edge.",
- "maximum": 10000,
- "minimum": 0,
- "type": "number"
- },
- "y": {
- "description": "Y in PDF points from the BOTTOM edge.",
- "maximum": 10000,
- "minimum": 0,
- "type": "number"
- }
- },
- "required": [
- "op",
- "page",
- "x",
- "y",
- "w",
- "h"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "additionalProperties": false,
+ "properties": {
+ "field": {
+ "description": "AcroForm field name.",
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+ },
+ "op": {
+ "const": "fill_field",
+ "type": "string"
+ },
+ "value": {
+ "anyOf": [
+ {
+ "maxLength": 2000,
+ "type": "string"
+ },
+ {
+ "type": "boolean"
+ }
+ ],
+ "description": "Text value, or a boolean for checkbox widgets."
+ }
+ },
+ "required": [
+ "op",
+ "field",
+ "value"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "color": {
+ "description": "6-digit hex colour, e.g. '#101014'.",
+ "pattern": "^#[0-9a-fA-F]{6}$",
+ "type": "string"
+ },
+ "fontSize": {
+ "maximum": 300,
+ "minimum": 1,
+ "type": "number"
+ },
+ "op": {
+ "const": "stamp_text",
+ "type": "string"
+ },
+ "page": {
+ "description": "1-based page number.",
+ "maximum": 500,
+ "minimum": 1,
+ "type": "integer"
+ },
+ "text": {
+ "maxLength": 2000,
+ "minLength": 1,
+ "type": "string"
+ },
+ "x": {
+ "description": "X in PDF points from the left edge.",
+ "maximum": 10000,
+ "minimum": 0,
+ "type": "number"
+ },
+ "y": {
+ "description": "Y in PDF points from the BOTTOM edge.",
+ "maximum": 10000,
+ "minimum": 0,
+ "type": "number"
+ }
+ },
+ "required": [
+ "op",
+ "page",
+ "x",
+ "y",
+ "text"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "color": {
+ "$ref": "#/properties/operations/items/anyOf/1/properties/color",
+ "description": "Fill colour of the box. Defaults to black."
+ },
+ "h": {
+ "description": "Rectangle height in points.",
+ "maximum": 10000,
+ "minimum": 1,
+ "type": "number"
+ },
+ "op": {
+ "const": "cover",
+ "type": "string"
+ },
+ "page": {
+ "description": "1-based page number.",
+ "maximum": 500,
+ "minimum": 1,
+ "type": "integer"
+ },
+ "w": {
+ "description": "Rectangle width in points.",
+ "maximum": 10000,
+ "minimum": 1,
+ "type": "number"
+ },
+ "x": {
+ "description": "X in PDF points from the left edge.",
+ "maximum": 10000,
+ "minimum": 0,
+ "type": "number"
+ },
+ "y": {
+ "description": "Y in PDF points from the BOTTOM edge.",
+ "maximum": 10000,
+ "minimum": 0,
+ "type": "number"
+ }
+ },
+ "required": [
+ "op",
+ "page",
+ "x",
+ "y",
+ "w",
+ "h"
+ ],
+ "type": "object"
+ }
+]Input schema / properties / pdfUrl / descriptionPrevious value: -"Publicly fetchable URL of a PDF Kamy has never seen. Kamy downloads it and stores it as a new render first. Supply exactly one of renderId or pdfUrl."New value: +"Publicly fetchable URL of a PDF Kamy has never seen. Kamy downloads it, applies the operations and stores only the edited result — the source does not become a separate render, and the call costs one render either way. Supply exactly one of renderId or pdfUrl."bulk_signature_requestscreate_signature_request8 fields changedInput schema / properties / placedFields / items / properties / anchor / descriptionPrevious value: -"Text anchor — server locates this string in the PDF and uses its position."New value: +"Text to position this field against. The server searches only the page named in `page` (case-insensitive, first match wins) and uses that text's bottom-left corner as the origin, adding x/y as offsets. If the text is not on that page the field silently falls back to the raw x/y — call preview_field_placement first to find out, where the miss comes back as an ANCHOR_NOT_FOUND issue."Input schema / properties / placedFields / items / properties / options / descriptionPrevious value: -"Valid choices for radio / dropdown."New value: +"Valid choices for radio / dropdown. Ignored for other types."Input schema / properties / placedFields / items / properties / signerLabel / descriptionAdded value: +"Which signer this field belongs to."Input schema / properties / placedFields / items / properties / sourcePageHeightAdded value: +{
+ "description": "Page height the coordinates were measured against. Supply with sourcePageWidth.",
+ "maximum": 7200,
+ "minimum": 72,
+ "type": "number"
+}Input schema / properties / placedFields / items / properties / sourcePageWidthAdded value: +{
+ "description": "Page width the coordinates were measured against. Supply with sourcePageHeight.",
+ "maximum": 7200,
+ "minimum": 72,
+ "type": "number"
+}Input schema / properties / placedFields / items / properties / type / descriptionAdded value: +"Widget the signer sees. `radio` and `dropdown` also need `options`. Every type here is accepted by both create_signature_request and preview_field_placement."Input schema / properties / placedFields / items / properties / x / descriptionPrevious value: -"Bottom-left x in PDF points."New value: +"Bottom-left x in PDF points — an offset from the anchor when `anchor` is set."Input schema / properties / placedFields / items / properties / y / descriptionPrevious value: -"Bottom-left y in PDF points."New value: +"Bottom-left y in PDF points — an offset from the anchor when `anchor` is set."create_templategenerate_integration_codeget_api_key_instructionsget_envelopeget_signature_requestget_signature_templateget_startedget_template_versionget_uploadget_usageinstall_sdklist_signature_templateslist_template_versionspreview_field_placementpublish_templateremind_signaturerollback_templatetrace_record_batchupdate_templatecreate_schedulecreate_webhookdelete_scheduleextract_from_renderget_accountget_jobget_renderget_render_pagesget_usagelist_renderslist_scheduleslist_webhooksrender_asyncrender_batchrender_xlsx1 field changedInput schema / properties / sheets / items / properties / columns / items / properties / boldRemoved value: -{
- "description": "Accepted for compatibility. The header row is always rendered bold on a tinted fill regardless of this flag.",
- "type": "boolean"
-}test_webhookattest_artifactconvert_documentcreate_envelopeedit_pdfget_provenance_chainmerge_pdfsrecord_agent_actionrender_docxrender_htmlrender_pptxrender_xlsxscan_tool_descriptionsplit_pdftrace_recordtrace_searchupload_fileverify_attestationverify_mcp_serverget_template_schemavalidate_payloadextract_documentcreate_signature_request10 fields changedInput schema / properties / authMethodAdded value: +{
+ "description": "Identity-verification mode. `link` (default) — possession of the secret URL is the only check. `email_otp` — sign page renders a 6-digit OTP gate; code emailed to `signerEmail`. `sms_otp` — same gate, code texted to `signerPhone` (which must then be supplied). Recommend `email_otp` for higher-value transactions.",
+ "enum": [
+ "link",
+ "sms_otp",
+ "email_otp"
+ ],
+ "type": "string"
+}Input schema / properties / ccEmailsAdded value: +{
+ "description": "Up to 10 observer addresses CC'd on the invite and the completion notice. Not signers themselves.",
+ "items": {
+ "format": "email",
+ "type": "string"
+ },
+ "maxItems": 10,
+ "type": "array"
+}Input schema / properties / expiresInAdded value: +{
+ "description": "How long (seconds) the sign link stays valid. Defaults to 30 days. Min 1 hour, max 30 days.",
+ "maximum": 2592000,
+ "minimum": 3600,
+ "type": "integer"
+}Input schema / properties / placedFieldsAdded value: +{
+ "description": "Up to 100 sender-defined fillable fields stamped onto the PDF at sign time. Use for flat PDFs that don't ship AcroForm widgets. Names must be unique.",
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "anchor": {
+ "description": "Text anchor — server locates this string in the PDF and uses its position.",
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+ },
+ "defaultValue": {
+ "maxLength": 2000,
+ "type": "string"
+ },
+ "h": {
+ "description": "Height in PDF points.",
+ "maximum": 800,
+ "minimum": 8,
+ "type": "number"
+ },
+ "name": {
+ "description": "Unique field name within the request.",
+ "maxLength": 120,
+ "minLength": 1,
+ "type": "string"
+ },
+ "options": {
+ "description": "Valid choices for radio / dropdown.",
+ "items": {
+ "maxLength": 200,
+ "minLength": 1,
+ "type": "string"
+ },
+ "maxItems": 50,
+ "minItems": 1,
+ "type": "array"
+ },
+ "page": {
+ "description": "1-indexed page number.",
+ "maximum": 500,
+ "minimum": 1,
+ "type": "integer"
+ },
+ "required": {
+ "type": "boolean"
+ },
+ "signerLabel": {
+ "maxLength": 200,
+ "type": "string"
+ },
+ "type": {
+ "enum": [
+ "text",
+ "textarea",
+ "checkbox",
+ "date",
+ "initials",
+ "radio",
+ "dropdown"
+ ],
+ "type": "string"
+ },
+ "w": {
+ "description": "Width in PDF points.",
+ "maximum": 800,
+ "minimum": 8,
+ "type": "number"
+ },
+ "x": {
+ "description": "Bottom-left x in PDF points.",
+ "maximum": 2000,
+ "minimum": 0,
+ "type": "number"
+ },
+ "y": {
+ "description": "Bottom-left y in PDF points.",
+ "maximum": 2000,
+ "minimum": 0,
+ "type": "number"
+ }
+ },
+ "required": [
+ "name",
+ "type",
+ "page",
+ "x",
+ "y",
+ "w",
+ "h"
+ ],
+ "type": "object"
+ },
+ "maxItems": 100,
+ "type": "array"
+}Input schema / properties / position / descriptionPrevious value: -"Optional stamp position in PDF points (72 dpi, origin bottom-left). Defaults to bottom-right of last page sized 220×64 pt."New value: +"Optional sender-chosen signature placement in PDF points (72 dpi, origin bottom-left). Defaults to bottom-right of the last page sized 220×64 pt; when omitted, the signer can drag the placeholder on the sign page."Input schema / properties / reminderCadenceHoursAdded value: +{
+ "description": "When set (24–168), the auto-reminder cron resends the invite every N hours while the request stays pending, up to 3 reminders. Omit for no auto-reminders.",
+ "maximum": 168,
+ "minimum": 24,
+ "type": "integer"
+}Input schema / properties / requireStampAdded value: +{
+ "description": "Require the signer to upload a company stamp / seal alongside their personal signature (UAE, KSA, JP, KR, IN, CN B2B workflows). Server refuses to seal without one.",
+ "type": "boolean"
+}Input schema / properties / signOnEveryPageAdded value: +{
+ "description": "When true, the server stamps the signer's signature on every page of the source PDF instead of only the configured position. Common B2B contract pattern.",
+ "type": "boolean"
+}Input schema / properties / signatureTemplateIdAdded value: +{
+ "description": "Apply a signature template's defaults (placedFields, position, message, expiresIn, ccEmails). Request-level fields override the template.",
+ "format": "uuid",
+ "type": "string"
+}Input schema / properties / signerPhoneAdded value: +{
+ "description": "E.164 phone number. Required when `authMethod` is `sms_otp`; ignored otherwise. Example: `+14155551234`.",
+ "pattern": "^\\+[1-9]\\d{6,14}$",
+ "type": "string"
+}get_signature_certificateask_kamycreate_signature_requestgenerate_integration_codeget_api_key_instructionsinstall_sdklist_signature_requestslist_templatespki_sign_pdfrender_pdfverify_pdf_signatureClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
E-signature API for AI agents: send contracts, sign PDF documents, track and download signed files.
Composable APIs for document extraction, image transformation, and document & sheet generation.
Send AI-created PDFs for signature, track signers, and return verifiable document evidence.
Cloud PDF generation from HTML, CSS and XSL-FO, with PDF/A and PDF/UA support.
Add one secure layer between your agents and this server.
Each tool targets a distinct action or resource with minimal ambiguity. For example, `render_pdf`, `render_docx`, `render_xlsx`, and `pptx` are clearly different output formats, while `merge_pdfs`, `split_pdf`, and `edit_pdf` target different PDF operations. The signature tools (`create_signature_request`, `get_signature_request`, etc.) are also clearly separated by lifecycle stage. No two tools appear to do the same thing.
Tool names follow a highly consistent `verb_noun` pattern throughout, such as `create_signature_request`, `get_signature_request`, `list_signature_requests`, and `remind_signature`. This pattern is applied uniformly across all major domains (render, signature, template, webhook, trace), making the API predictable and easy for an agent to navigate.
With 59 tools, this is a large surface area, but it is justified by the breadth of functionality: document rendering in multiple formats, e-signatures, template management, webhooks, scheduling, and a crypto/audit trail. While large, each tool has a distinct purpose, and the count feels appropriate for the scope of a comprehensive document automation API. A surface this large risks being overwhelming, but the internal organization is logical.
The tool surface is remarkably complete, covering the full lifecycle for multiple domains. For e-signatures, there are tools for CRUD (requests, templates), sending (individual, bulk, envelope), monitoring (get, list), reminders, and certificates. For documents, it covers creation, conversion, editing, merging, splitting, and verification. The inclusion of utility tools like `get_started`, `validate_payload`, and the audit trail tools further solidifies this as a well-considered, production-ready API surface.
