Other PDF MCP servers ask you to install Chrome, manage a local renderer, and ship templates yourself. Kamy MCP is a hosted endpoint — point any MCP client at https://mcp.kamy.dev/mcp, paste an API key, and start asking your AI to "generate an invoice for Acme Corp". Eight production-ready templates ship with the service (invoice, quote, receipt, contract, agreement, certificate, report, shipping-label)
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 readOnlyHint and non-destructive behavior. Description adds that it sends to a public endpoint and returns a paragraph answer, providing useful 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?
Two sentences with no wasted words; purpose is stated first, followed by technical details. 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?
For a simple read-only tool with one parameter and no output schema, the description explains the action, endpoint, and response format fully. 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 has 100% description coverage and includes example topics. Description does not add extra parameter details beyond what the schema provides, meeting the baseline expectation.
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 uses specific verb 'Ask' and resource 'Kamy Brain', lists example topics, and clearly differentiates from sibling tools that perform specific actions like signing or PDF generation.
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?
Description indicates it's for asking questions about Kamy usage and returns an answer. While it doesn't explicitly state when not to use, the read-only annotation and sibling context make usage 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?
Description explains the tool hashes bytes, returns specific fields, and explicitly states what the attestation proves and does NOT prove (no correctness claim). Annotations are minimal (no readOnlyHint or destructiveHint), but description fully discloses behavior. Could note whether it is rate-limited or requires specific permissions beyond API 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?
Single paragraph is front-loaded with the core action, then parameter guidance, then return value summary, then caveat. Every sentence adds value without redundancy. No 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 the complexity (9 params, nested objects, mutual exclusivity), the description covers all key aspects: use case, parameter selection, return fields, and limitations. No output schema exists, but the return shape is described. The caveat about not claiming correctness is particularly valuable.
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 each parameter well-described. The description adds value by clarifying the mutual exclusivity of content parameters and the hashing behavior. It does not repeat parameter descriptions, instead providing functional context. Loses a point because it doesn't mention the 'tags' or 'metadata' use cases beyond what 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?
Description clearly states the tool cryptographically signs agent outputs (PDF, report, etc.) for later verification. Uses specific verb 'sign' and resource 'artifact', and distinguishes it from siblings like 'verify_attestation' and 'pki_sign_pdf' by focusing on recording proof of origin.
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 each content parameter: pass content_text or content_base64 when content can leave environment, or content_sha256 when it must not. Also tells the agent to hand verify_url to third parties. No sibling alternatives are directly contrasted, but the usage scenarios are clear.
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 only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description goes far beyond by detailing: duplicate email rejection (422), per-signer failure handling (207 with structured response), quota consumption ('consumes one signature per signer' with free tier details), required API scope ('signatures:write'), and auth fallback ('without a key, returns dashboard setup instructions'). 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 dense but not bloated — every clause adds value. It front-loads the core action and use-case, then layers on behavioral details, error handling, quota notes, and auth. A minor point: the quota explanation ('free tier: 10 per month...') could be slightly more concise, but it earns its place by preventing costly mistakes.
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 (6 parameters, nested objects, batch + quota + auth concerns, no output schema), the description covers the most critical gaps: partial failure model, response shape, quota exhaustion, and auth scope. Loses one point because it doesn't describe the reminderCadenceHours default behavior (it says 'up to 3 reminders' but not whether 0 cadence disables them) and doesn't explicitly state whether expiresIn has a default (it does from schema: 7 days).
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%, but the description adds crucial context beyond property descriptions: it explains the shared position rectangle, the per-signer CC behavior, the uniqueness constraint on signerEmail (duplicate 422), the reminder cadence limit (up to 3 reminders), and the substitution template for message ({{signerName}}). This enriches every parameter with real usage 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 ('fan out') and resource ('already-rendered PDF to up to 100 independent signers'), immediately distinguishing it from siblings like create_signature_request and create_envelope. It clearly states what the tool does and contrasts with a sibling ('Choose create_envelope instead when...').
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 explains when to use this tool (unrelated parties each signing their own copy) vs when to use create_envelope (same document together with routing). It also notes that duplicate signer emails are rejected (422) and covers batch behavior (partial failures, response format, per-signer quota consumption).
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?
Annotations already indicate non-readOnly and non-destructive. The description adds significant behavioral context: quota consumption (1 render), file size limit (10 MB), authentication requirement (render scope key), and return structure (id, url, bytes, durationMs, name). 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?
Single focused paragraph, logically ordered: purpose, input method, contrast with siblings, return type, quota/size/auth. Every sentence adds meaningful information. 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?
While no output schema exists, the description adequately covers return structure and error conditions (size limit, auth failure). It mentions quota consumption and API key scope. Minor lack: no mention of error behavior for invalid file content. Still very complete given 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?
Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that the filename is used for input type detection and that the 'name' parameter defaults to the source filename. This clarifies usage 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 converts .docx, .xlsx, or .csv files to PDF, preserving content. It distinguishes from sibling generation tools like render_docx by emphasizing the 'inbound direction'. The verb 'Convert' and resource 'file to PDF' 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 (converting existing documents) vs. alternatives (generating from data via render_* tools). Also provides practical constraints: files over 10 MB refused, counts against monthly quota, requires API key with `render` scope. Clear guidance on when not to use and prerequisites.
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?
The description discloses several behavioral traits beyond the annotations: preview mode skips email and quota, real send emails immediately and consumes one signature per recipient, quota limits ('free tier: 10 signatures/month'), and the return shape ('{ envelope, recipients: […] } with a sign_url per recipient'). This fully informs the agent of side effects, costs, and responses. No contradiction with annotations (readOnlyHint=false, destructiveHint=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 a dense single paragraph that covers all key points without fluff. Every sentence serves a purpose. However, it could be more scannable with bullet points or line breaks for the auth note and return shape. Still, it's tightly written and front-loads the core 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 10 parameters (including a complex nested recipients array and placedFields), no output schema, and sibling tools, the description addresses the main workflow: source selection, routing, preview mode, real send effects, and return value. It doesn't cover every edge case (e.g., what happens if signer order is omitted in sequential mode) but provides sufficient guidance for correct use. The lack of output schema is compensated by stating the return shape explicitly.
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% (all 10 parameters have descriptions), so the baseline expectation is 3. The description adds meaningful context: explains the exclusivity of renderId/pdfUrl, details routing behavior beyond enum values, clarifies preview flag purpose, and notes the per-recipient message override. It doesn't repeat schema boilerplate but offers practical guidance, 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 precise verb-resource pairing: 'Send a single PDF to 2–10 signers as one envelope.' It immediately distinguishes this tool from the sibling create_signature_request by calling it the 'multi-signer counterpart' and explaining the API rejects fewer than two recipients. This leaves no ambiguity about what the tool does or when to choose it.
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 ('pick the tool by signer count') and when not to (fewer than 2 signers → use create_signature_request). It also explains routing modes with concrete scenarios ('parallel… each signs independently', 'sequential… approve-then-countersign chains'). Prerequisites ('Kamy API key with signatures:write scope') and the alternative without a key ('returns dashboard setup instructions') are clearly provided.
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?
The description adds significant behavioral details beyond the sparse annotations: it explains that the cron expression is evaluated in a given IANA timezone, that firing intervals are plan-gated with specific minimums (Free: 60 min, Starter: 15, Pro+: 5), that invalid intervals are rejected with a validation error naming the limit, and that each firing consumes a monthly quota. It also mentions the return value (id and next_run_at). 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 paragraph that is dense yet well-structured. It front-loads the core purpose, then provides usage guidance, then behavioral details. Every sentence adds unique information (cron, timezone, plan limits, quota, channel options, return value). There is no wasted word—it earns its length through efficient conveyance of critical 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?
Given the tool's complexity (9 parameters, 4 required, nested objects, no output schema, 44 sibling tools), the description covers all essential aspects: purpose, when to use vs. render_pdf, channel specifics, plan constraints, quota impact, default value for 'enabled', and return value. It even mentions validation errors. The description is self-contained and provides enough context for an agent to decide when and how 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?
The input schema has 100% description coverage, so the baseline is 3. The description adds value beyond the schema by explaining the plan-gating for the 'schedule' parameter (specific intervals per plan) and the quota implications. It also reinforces the conditional nature of 'recipients' based on the channel. While the schema already describes the enums and requirements, the description provides richer operational 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 tool's purpose: 'Set up a recurring render: a cron expression, a template, and where each document goes.' It immediately distinguishes this from the sibling render_pdf by stating 'Use this instead of render_pdf when the user wants a document produced repeatedly on a calendar.' This provides a specific verb+resource and differentiates it from alternatives.
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 ('instead of render_pdf'), provides examples ('weekly report, monthly invoice run'), and details the channel options with their requirements ('email' and 'whatsapp' require recipients; 'download' does not). It also warns about plan-gated intervals and quota consumption, giving clear context for when to use and what constraints apply.
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 indicate readOnlyHint=false (write operation) and destructiveHint=false. The description adds the key behavioral trait that an API key is required for execution, and that without it the tool returns setup instructions. This provides useful context beyond the annotations without contradicting them.
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 primary action. Every word contributes value, and there is no redundancy or filler. Perfectly concise for a tool with rich schema documentation.
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 full schema coverage, the description is too brief for a complex tool with 14 parameters, nested objects, and no output schema. It omits high-level workflow context such as the role of renderId (must come from render_pdf), the fact that the signer receives an email invitation, and how response behaves. The description does not adequately prepare the agent for the full sequence of events.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes all 14 parameters in detail. The description does not add any parameter-level meaning or usage hints. Baseline of 3 applies because the schema does the heavy lifting.
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 previously rendered PDF for e-signature, using a specific verb and resource. It adds a conditional about API key configuration, making the purpose precise. However, it does not differentiate from sibling tools like bulk_signature_requests, so it loses a point for lack of sibling distinction.
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 tells when to use the tool (when a Kamy API key is configured) and what happens without it (returns setup instructions). It does not provide explicit guidance on when not to use or mention alternatives such as bulk_signature_requests for multiple signers, making the usage context implied rather than fully explicit.
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 only provide readOnlyHint=false, destructiveHint=false, but the description goes far beyond: explains the paid feature restriction (403 on Free plan), slug uniqueness constraints, new template versioning behavior (no published version initially), and required auth scope. No contradiction with annotations — description adds rich context annotations don't cover.
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, front-loaded with the core action and key parameters, then progressively adds constraints, error handling, and auth. Every sentence provides unique, actionable information. 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 a creation tool with 8 parameters, no output schema, and a non-trivial versioning model, this description is remarkably complete. It covers what the tool does, prerequisites, failure modes, how to fix collisions, and the relationship to sibling tools. The only minor gap is no mention of the return value or response format, but this is acceptable given the complexity is well covered elsewhere.
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 relationship between slug and render_pdf, the versioning lifecycle, and the error conditions (403, 422), which the schema's property descriptions do not cover. It could also briefly explain how `schema` and `isPublic` are used, but the schema descriptions are already clear.
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 verb 'Create', the resource 'custom PDF template', and key attributes (name, slug, Handlebars/HTML body, optional CSS/schema). It clearly distinguishes from siblings like update_template, publish_template, and render_pdf by explaining the slug lifecycle and when each tool applies.
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?
Excellent usage guidance: explicitly says when NOT to use it (Free plan → 403), what to do if slug is taken (use update_template, not retry), and mentions API key scope requirement. This directly helps an agent decide between this tool and siblings like update_template or publish_template.
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?
The description goes far beyond annotations (which only indicate non-readonly, non-open-world, non-destructive) by disclosing: the one-time signing secret must be surfaced and stored immediately, default events, the full event set including wildcard acceptance, and rejected private/loopback hosts. It warns that localhost tunnels won't work, adding critical behavioral 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 a single paragraph covering all key points but could be slightly more structured (e.g., bullet points for events). It is front-loaded with the core purpose and usage guidance. Every sentence adds value, but the event list is a bit verbose inline.
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, no output schema, and annotations only cover nondestructive/non-readonly flags, the description completely covers usage context, event semantics, secret handling, and URL constraints. The agent has all information needed to invoke it correctly without additional help.
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 description coverage, the schema already documents all three parameters well. The description adds value by explaining the one-time signing secret behavior (not in the schema) and clarifying that the event set is open-ended ('any other string is accepted'). However, it doesn't describe the enabled parameter's purpose beyond what the schema says, keeping the score slightly below 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 clearly states the tool registers an HTTPS endpoint for Kamy to POST to when work finishes, distinguishing it from polling-based alternatives like get_job or list_renders. The verb 'register' and resource 'HTTPS endpoint' are specific, and the sibling context reinforces the 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 explicitly says 'Use this when the caller owns a server that can receive callbacks; use get_job or list_renders when it cannot,' providing clear when-to-use and when-not-to-use guidance with named alternatives. This directly helps the agent decide among siblings.
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 include destructiveHint: true, so the destructive nature is declared. The description goes beyond by explaining 'no undo and no trash,' safety steps (recreate with create_schedule), and impacts on other resources: 'Documents already produced by past firings are unaffected and remain available through list_renders.' 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 (3 sentences plus return info) and front-loaded with the core purpose. Every sentence adds value: deletion behavior, undo mechanism, pause alternative, and effect on documents. Slightly longer than needed for the return value detail, 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 the tool's simplicity (single parameter, no output schema, annotations present), the description fully covers what an agent needs: what it does, safety warnings, alternative actions, and return behavior. 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?
The input schema covers 100% of parameters with a description for schedule_id. The description adds value by stating the return format '{ deleted: true }, or 404 if the id does not belong to this account' and referencing how to obtain the id from create_schedule or list_schedules, which is useful context 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 explicitly states 'Permanently delete a recurring schedule so it stops firing,' using a clear verb (delete) and resource (schedule). It differentiates from sibling tools like create_schedule and list_schedules by explaining what it does uniquely.
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: 'confirm with the user before calling this on a schedule you did not just create.' It also clearly states when not to use it: 'If the intent is only to pause it, do not use this tool,' and offers an alternative (enabled flag via REST). This covers exclusions and alternatives comprehensively.
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 already indicate the tool is not read-only (readOnlyHint: false) and not destructive (destructiveHint: false). The description adds rich behavioral context: operations are applied in order, the source document is untouched and a new render is created, 'cover' only hides content visually without deleting bytes (and carries a COVER_VISUAL_ONLY warning), AcroForm values are flattened by default, and there is no redaction operation ('op: redact' is rejected). This goes well beyond the annotations and fully discloses the tool's behaviors and limitations.
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 contributes necessary information. It is front-loaded with the core purpose and operations, then covers parameters, behavior, error handling, and prerequisites. It could be slightly more concise by omitting some redundancy (e.g., the cover operation explanation appears both in the top-level description and in the operations parameter description), but overall it is well-structured and informative without being wordy.
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 states the return fields: '{ id, url, bytes, durationMs, name, warnings }' and explains the importance of reading warnings. All five parameters are fully documented in the schema, and the description adds behavioral context for each. The tool's complexity (multiple operation types, two exclusive input sources, API key requirements, non-destructive vs visual-only actions) is thoroughly covered. The description leaves no major gaps for the agent to infer.
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 meaning beyond the schema: it explains that coordinates use PDF points with origin at BOTTOM-left, that flattenFields defaults to true (with guidance on when to set false), that operations must be supplied in order, and that the warnings field must be read because out-of-range pages and unmatched field names are reported there rather than failing. These details are critical for correct usage and are not present in the schema descriptions alone.
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 ('Modify an existing PDF') and specifies the three operations: fill AcroForm fields, stamp text, paint opaque boxes. It distinguishes from the sibling tool render_pdf by contrasting when to use each: 'Use this when a document already exists... use render_pdf when the document should be generated from a template instead.' It also mentions downstream tools that consume the result, further clarifying the tool's role in the workflow.
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 guidance: '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.' It also gives when-not-to-use guidance for the 'cover' operation: 'never use it to hide secrets or personal data... it is NOT redaction.' The description explains the exclusive source parameter choice, the need for an API key with `render` scope, and how errors are reported (via warnings). All this helps the agent select the right tool and use it correctly.
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?
Annotations show readOnlyHint=false and destructiveHint=false. The description adds the output (parsed JSON + verify URL) but does not clarify if state changes occur (e.g., storing extracted data). Since annotations already hint at non-read-only behavior, the description should ideally explain any side effects or stored state.
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 with no filler. First sentence covers purpose and output, second provides usage guidance. Every word 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?
Given no output schema, the description adequately mentions return values (parsed JSON + verify URL). It does not detail template-specific fields or error handling, but the tool is fairly simple with 3 params and no nested objects.
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 each parameter described. The description adds no further parameter details 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 states it extracts structured data from PDFs, lists document types (invoice, receipt, contract, ID document, or any form), and mentions return values (parsed JSON plus verify URL). The verb 'extract' combined with the resource (document) is specific, and it distinguishes from siblings as the only extraction 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 explicitly says 'Use this when an agent needs to read an inbound document and act on it,' providing clear context. It lacks an explicit 'when not to use' or alternatives, but no direct sibling competes for this purpose, so it's sufficient.
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?
Beyond the readOnlyHint=true annotation, the description adds concrete behavioral traits: 'without uploading anything', 'spends no render quota and no extraction credits', and the specific error return '409 RENDER_NOT_READY' when the render isn't successful. It also details the two output modes, which is rich contextual information.
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, dense paragraph. Every sentence earns its place: purpose, modes, alternative guidance, resource traits, and error condition. It is front-loaded with the core purpose and avoids 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?
Despite having no output schema, the description fully explains return shapes (per-page text plus fullText; fields as name/type/value), error behavior, resource usage, and the distinction from sibling tools. For a tool with only 2 parameters, this is complete and self-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?
The schema already describes both parameters fully (100% coverage). The description adds extra meaning by explaining that type='fields' reveals what edit_pdf can fill in, and by detailing the return structures for both types. This enriches parameter semantics beyond the schema's descriptive text.
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 'Read' and clearly states the resource: 'the text or the form fields back out of a document this account already rendered.' It distinguishes from sibling extract_document by explicitly saying when to use extract_document instead, 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 explicitly provides when-to-use: 'Choose extract_document instead when the PDF came from outside Kamy or when you need AI-structured JSON against a schema.' It also clarifies the mechanical read nature, resource usage (no quota/credits), and the precondition that the render must have status 'success'.
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 provide readOnlyHint=true, but the description adds significant behavioral details: read-only, spends nothing, works with any valid API key regardless of scopes. It also clarifies edge cases like 'quota and remaining are null on unmetered plans, which means unlimited, not zero' and watermark policy behavior. This goes well 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 fairly long but every sentence serves a purpose. It is front-loaded with the core purpose and then expands with specific usage details and warnings. A slight reduction in wordiness could improve readability, but it is well-structured and informative.
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 zero parameters and no output schema, the description provides complete context. It explains what is returned (profile, plan, limits, usage, watermark), how to interpret null values, and why the tool is needed before other operations. There are no gaps in understanding how to use or interpret 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?
The tool has zero parameters, so parameter semantics are trivially satisfied. The description adds no parameter meaning because none exist, but it does cover all aspects of the tool's behavior. Per the rubric, 0 params gets a baseline of 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 'Read everything about the authenticated Kamy account in one call' and enumerates specific items (profile, plan, limits, usage, watermark). It distinguishes itself from siblings by explicitly noting 'This is the only tool that answers any of those questions — there is no separate quota tool.' This provides a specific verb+resource scope with 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 explicitly tells when to use the tool: 'Call it before render_batch, create_schedule, or any long series of renders.' It also explains what to check (usage.renders.remaining) and the consequence of quota exhaustion ('every render tool fails with 402 QUOTA_EXCEEDED'). This provides clear when/why 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 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?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context beyond annotations: it confirms read-only behavior explicitly, notes it spends no quota, describes sequential routing behavior ('recipients whose turn has not arrived show status waiting'), and specifies required API scope ('signatures:read') plus the authentication failure behavior ('without a key, returns dashboard setup instructions'). The only minor gap is not documenting potential error responses for invalid envelope IDs.
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 and return data. Every sentence adds distinct value: what the tool does, what it returns, when to use it (and when not to), behavioral details (sequential routing, waiting status), read-only guarantee, and authentication 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 only one required parameter with full schema coverage, no output schema, and no nested objects, the description is remarkably complete. It covers purpose, return fields, usage context, behavioral nuances, auth scope, and edge cases (no key behavior). There is no obvious gap that would hinder an agent from correctly using 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 one parameter (envelopeId) already well-described in the schema. The description reinforces this by mentioning that the ID comes from create_envelope. While the description doesn't add new parameter details, the schema is already complete, so the baseline of 3 applies, and the mention of the source (create_envelope) provides useful cross-tool context, justifying 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 starts with a clear verb ('Fetch') and a specific resource ('one multi-signer envelope'), then lists exactly what data is returned (recipients with sign_url, status, etc.) and the envelope's own status. It explicitly distinguishes itself from the sibling tool 'get_signature_request' by noting that tool returns no recipient list.
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 tells the agent exactly when to use this tool ('who still has not signed? after a create_envelope send'), and when to use an alternative ('get_signature_request answers that for a single standalone request and returns no recipient list'). This is exemplary contextual guidance.
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?
Beyond annotations (readOnlyHint, destructiveHint), the description adds detailed return schema, polling behavior, and expiration handling. It discloses the tool's read-only nature and quota implication, fully transparent.
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 with high information density. Front-loaded with purpose, then return details, then usage advice. 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?
For a single-parameter tool with no output schema, the description fully explains the return structure, statuses, conditional fields, and lifecycle. It's complete and self-contained.
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 has 100% coverage and describes job_id as 'The jobId render_async returned.' The description echoes this without adding new meaning. Since schema coverage is high, baseline is 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 polls an asynchronous render job started by render_async. It specifies the return structure with statuses and conditional fields, distinguishing it from related tools like get_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?
Explicitly says to poll every few seconds, not in a tight loop, and mentions typical duration. Provides alternative (get_render) for expired URLs. States it's read-only and spends no quota, guiding appropriate usage.
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=true and destructiveHint=false, and the description confirms read-only, adds the return structure with chain_intact verdict, and notes the API key requirement. No contradictions, and extra context elevates 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?
Two sentences plus one sentence for returns, all front-loaded with the core action and use case. Every word earns its place 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 no output schema, the description provides the full return structure and the meaning of chain_intact. It covers purpose, usage, parameters, requirements, and safety, making it complete for the tool's 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?
Schema coverage is 100% with a clear description for run_id. The description adds context by specifying that run_id comes from attest_artifact/record_agent_action, which adds meaning beyond the schema's generic 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 replays artifacts and calls under a run_id with order and parent hash links, and provides specific use cases (incident review, handover, audit). It distinguishes itself from sibling recording and trace 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 explicitly says 'Use it to answer...' and lists three contexts, along with read-only and API key requirements. It lacks explicit contrast with alternative trace tools like trace_record or trace_search but implies the unique purpose of chain verification.
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?
The description significantly adds behavioral context beyond the readOnlyHint and destructiveHint annotations. It explains the freshly signed URL expiry, the fact that calling again on an old render yields a working download, the conditions when url is null, and that it's read-only with no quota usage. 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 well-structured and front-loaded: the first sentence states the core action. Subsequent sentences add valuable context without redundancy. Every sentence earns its place, covering recovery path, usage guidance, return format, and caveats in a concise manner.
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 highly complete. It explains the return structure, when url is null, and the security aspect of fresh URLs. It covers the main use case and edge cases (failed, unfinished, aged out files) adequately.
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 detailed description for render_id listing its origins. The tool description does not add new meaning beyond what the schema provides, so the baseline score of 3 applies. No extra parameter details are added.
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 'Fetch' and the resource 'one previously produced document by its render id'. It distinguishes from sibling tools by explicitly mentioning to use list_renders if the id is unknown, and implies it's the recovery path for expired links, differentiating it from get_render_pages or render_pdf.
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 when you have a render id and want a fresh download URL, and use list_renders when you don't have the id. It also notes it's read-only and spends no quota. However, it does not exclude other scenarios like when multiple pages are needed, which could be handled by get_render_pages.
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?
The description adds significant behavioral context beyond the annotations (readOnlyHint=true, destructiveHint=false). It reveals that repeated calls overwrite page images (safe to retry), that rasterisation costs no render quota, and the 409 error condition. 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 three sentences, front-loaded with the core action, then usage guidance, then behavior details. Every sentence is informative and necessary. 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 the tool has only two parameters and no output schema, the description is fully complete. It covers the purpose, usage guidelines, prerequisites, error handling, idempotency, quota impact, and the return format (pages array with fields). 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 the schema already documents both parameters. The description mentions the dpi defaults and range, but this information is also present in the schema's description field. The description does not add new semantic meaning beyond what the schema provides, so a baseline score 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 clearly states the verb 'rasterise' and the resource 'every page of an existing render to a PNG image'. It distinguishes itself from the sibling tool 'extract_from_render' by specifying the use case: visual vs. text extraction. This is a specific and unambiguous 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 tells when to use this tool ('thumbnails, previews, visual QA') and when to use the alternative 'extract_from_render' for text. It also provides a clear prerequisite: the render must have status 'success', and explains the error response for non-ready renders. This is excellent guidance.
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 that the result is a URL, explains the terminal state requirement, and mentions a potential error response (409) for pending requests. 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?
Two sentences that front-load the primary purpose and then add conditions. Every sentence serves a purpose with no 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?
With one parameter, strong annotations, and no output schema, the description covers all necessary context: what it returns, preconditions (terminal state), and fallback behavior (setup instructions). 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 has 100% coverage with a description for signatureRequestId. The description adds essential context: that the ID must belong to a request in a terminal state, and that pending requests return a 409 error. This goes beyond the schema's format and type info.
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 explicitly states it returns the authenticated download URL for a Certificate of Completion PDF, an audit trail. This clearly distinguishes it from sibling tools (e.g., list_signature_requests, 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?
Description notes the tool is only available after the request reaches a terminal state and that without a key it returns setup instructions. While it doesn't explicitly list when not to use, the terminal state constraint provides clear guidance, and sibling tools do not overlap.
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?
Annotations already set readOnlyHint=true, and the description reinforces this with 'Read-only and spends no quota.' It adds auth requirements ('signatures:read' scope) and the dashboard-setup behavior without a key, plus explains status enum semantics. This goes well beyond the bare 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 core action, then expands with details, usage guidance, status notes, and auth requirements. Every sentence contributes necessary information without redundancy—efficient and well-structured despite being longer than average.
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, read-only retrieval tool with no output schema, the description covers purpose, data richness, alternatives, status semantics, auth, and quota effects. It's fully self-contained and leaves no obvious questions unanswered.
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 parameter description already explains where the id comes from ('Returned by create_signature_request, bulk_signature_requests, or a list call'). The tool description doesn't add additional meaning beyond what the schema provides, so 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 and resource ('Fetch one signature request by id') and immediately distinguishes itself from siblings by noting 'the detail list_signature_requests leaves out' and contrast with get_signature_certificate. It clearly defines the tool's scope and unique value.
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 names alternatives and when to use them: '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.' It also clarifies the 'waiting' status, preventing misinterpretation.
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 and destructiveHint=false. The description adds value by stating 'Read-only and spends no quota' and specifying the required auth scope ('signatures:read') and behavior 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?
Three sentences, each serving a distinct purpose: (1) stating what the tool does and its unique value, (2) listing use cases, (3) noting behavioral/property traits. No redundancy or filler. Front-loaded with the core 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?
Given the tool has only one parameter, no output schema, and annotations cover safety, the description adequately covers purpose, use cases, and auth. It hints at the return structure ('placed_fields array and position'). While it could more explicitly describe the full response object, the description is sufficient for a simple fetch operation.
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 single parameter has a description: 'ID from list_signature_templates.'). The description does not provide additional details about the parameter beyond what the schema already offers, so the baseline score 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 uses a specific verb ('Fetch') and clearly identifies the resource ('one e-signature preset in full'). It explicitly distinguishes from the sibling tool list_signature_templates by noting that list_signature_templates omits the placed_fields array and position. This provides strong 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 provides concrete use cases: inspect or copy field layout before applying via create_signature_request, or as starting point for preview_field_placement. It also notes read-only and no quota, which implies appropriate contexts. However, it does not explicitly state when NOT to use this tool or name alternatives beyond the implicit ones.
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?
The description explicitly states 'Pure text: it makes no API call, reads no account state, and needs no API key', which directly confirms annotations (readOnlyHint=true, destructiveHint=false) and adds valuable behavioral details about side effects and requirements 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 a single dense paragraph that front-loads purpose and progressively adds detail about parameters and usage conditions. Every sentence adds unique value with 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 the tool is simple (0 required params, no output schema, no nested objects), the description covers all needed aspects: purpose, usage guidance, parameter semantics, and behavioral boundaries. It is fully complete for an introductory/onboarding 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%, yet the description adds meaning by explaining how parameters interact (e.g., 'template requires framework', 'packageManager ignored for Python stacks'). It also explains the conditional behavior of each parameter and their practical impact on the output sections.
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 ('get started') and names the exact resources (API key steps, install commands, client-setup snippet, route handler). It clearly distinguishes this tool from its siblings by stating it replaces install_sdk, generate_integration_code, and get_api_key_instructions, and its output is generated text, not a rendered document.
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 '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'. It also tells you to call list_templates first if you don't know the slug, providing clear when-to-use guidance.
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 indicate readOnlyHint=true and destructiveHint=false. Description adds value by stating 'No authentication required' and the recommended usage sequence, without contradicting 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?
Two succinct sentences, front-loaded with main purpose. No unnecessary words; each sentence adds relevant 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 simple one-parameter tool with no output schema, the description covers purpose, usage timing, and authentication. No gaps given the low 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?
Single parameter 'slug' is fully described in schema with examples. Description does not add additional semantic details beyond what schema provides, 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?
Description clearly states it fetches JSON schema and sample payload for a template, with specific verb 'Fetch' and explicit mention of resource. Distinguishes itself by advising to call before render_pdf, differentiating 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?
Explicitly says to call before render_pdf and notes no authentication required. Provides clear context for when to use, though lacks explicit when-not or alternative exclusions.
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?
Annotations already declare readOnlyHint=true, destructiveHint=false. The description adds meaningful behavioral context beyond annotations: it explicitly states 'Read-only and spends no quota', clarifies that it returns a frozen snapshot (a behavioral trait not inferable from readOnlyHint alone), and documents authentication requirements ('Kamy API key with templates:read scope') and the error path ('returns dashboard setup instructions' when missing a key). A 5 would require additional details like pagination limits or rate-limit behavior.
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 packs a lot of useful information into three sentences without wasted words. The first sentence front-loads the core action and returned fields. The second provides usage guidance and pairing with sibling tools. The third covers parameter semantics and auth requirements. Loses one point because the sentence is slightly dense (multiple semicolon-separated ideas in the second sentence), making parsing slightly harder.
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 low complexity (2 required params, no nested objects), 100% schema coverage, no output schema (so description correctly doesn't explain return values), and comprehensive annotations, the description is fully complete. It covers purpose, when to use, what not to do, how to pair with siblings, parameter acquisition workflow, authentication, quota impact, and error behavior. There are no gaps given the tool's scope.
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 explaining the semantics of 'version' relative to list_template_versions (the step-by-step workflow for obtaining it), and clarifies that templateId accepts 'UUID or slug'. This extra workflow context raises the score above baseline. A 5 would require explicit mention that both parameters together uniquely identify the snapshot, or more format constraints.
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 uses the verb 'Fetch' with the resource 'one template version snapshot in full', followed by a precise list of fields (html, css, schema, createdBy, createdAt). It clearly distinguishes the snapshot nature ('exactly as it was frozen') from other template operations, and its purpose is unambiguous even among 50+ 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 explicit when-to-use guidance ('list_template_versions first to find the number'), specific use cases ('inspect what a released version actually contained', 'recover content a later draft edit overwrote'), and crucially tells the agent what to use next if a mutation is needed ('pair it with rollback_template when you want that version live again'). It also states what the tool does not do ('changes nothing on its own').
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?
Beyond the annotations (readOnlyHint, destructiveHint), the description reveals a key behavioral trait: the tool reconciles a pending row against storage and flips it to 'uploaded' on first success. It also discloses the 1-hour signed URL validity, auth requirements (uploads:read scope), and that it spends no quota. This is rich, non-obvious information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with front-loaded core information. Every sentence adds value, though it could be slightly tighter (e.g., the note about dashboard setup without a key could be split or placed last). Still, no waste.
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 only one parameter and no output schema, the description adequately covers return values, side effects, authentication, and use cases. It explains the reconciliation behavior, signed URL expiration, and the scope requirement. This is a complete description for a simple but nuanced 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?
The input schema already describes the uploadId parameter with format and length. The description adds critical clarification: 'The bare UUID, not the kamy://asset/... ref.' and points to upload_file as the source. This is meaningful 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 looks up a stored asset by upload ID and lists the returned fields (filename, contentType, sizeBytes, status, etc.). The verb 'look up' paired with the resource 'stored asset' is specific and distinct from sibling tools like upload_file or get_document.
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 its main use is confirming an out-of-band transfer landed and minting a fresh download link after expiry. It references upload_file as an alternative when the file is too large for inline transfer. This provides clear context, though it stops short of listing all situations where this tool should not be used.
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?
Annotations already indicate readOnlyHint: true and destructiveHint: false, so the description does not need to repeat that. Beyond annotations, it discloses that returned URLs are signed and expire after an hour, which is critical behavioral information not captured elsewhere. The description also notes it's read-only and spends no quota. It could be slightly more explicit about pagination behavior, but overall excellent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: starts with the core purpose, then explains when to use it, then provides behavioral details and return format. Each sentence adds meaningful content. Slightly verbose in the middle but not unwieldy.
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 only 2 optional parameters, a clear schema, and robust annotations, the description is largely complete. It explains the return format, URL expiration, and how to use with siblings. It lacks explicit mention of rate limits or whether the user needs specific permissions, but these are minor 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% for both parameters, so the baseline is 3. The description does not add significant meaning beyond what the schema already provides for the pagination parameters. It explains the overall use case but not parameter-specific nuances.
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 lists documents produced by the account, newest first. It distinguishes itself from siblings like get_render by explicitly explaining its role in finding previously rendered PDFs whose URLs have expired.
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 made in a previous turn, by a schedule, or by another process and the original URL has expired. It also mentions the alternative: use get_render with the id to mint a fresh URL.
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 provide readOnlyHint: true and destructiveHint: false, and the description adds value by stating 'Read-only and spends no quota,' which is not derivable from annotations alone. Also explains what each field in the response represents, especially the diagnostic relevance of last_run_error.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and ordering, then follows with usage guidance and field details. Slightly wordy in the middle section listing fields—could be tightened without losing meaning, but overall efficient for the information conveyed.
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 documents return fields (schedules, total, limit, offset) and explains key schedule row attributes. The tool is simple (2 optional params, no nested objects), and the description covers all aspects needed for correct invocation and interpretation.
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 implying that the tool supports pagination (returns offset and limit in response) and confirms default values (limit defaults to 50, offset to 0) though not explicitly stated. A small deduction because the description does not directly tie limit/offset to pagination behavior or explain the return structure fully.
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 ('List') and resource ('recurring render schedules') while distinguishing from siblings like create_schedule and delete_schedule by mentioning the id needed for deletion. Scope is confined to 'this account' and ordering is explicitly '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?
Explicitly states when to use: before creating a duplicate schedule and for diagnosing a non-producing schedule. Lists what each row contains (enabled, schedule, timezone, etc.) and clarifies that last_run_error shows delivery or quota failures, giving the agent clear decision rules.
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=true and destructiveHint=false. The description adds behavioral context by specifying that without an API key, the tool returns dashboard setup instructions, which is 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 two sentences with zero waste: first states the core function, second adds crucial context about key dependency. Every sentence is necessary.
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 no output schema and simple parameters (2 optional), the description explains ordering and key behavior. It omits exact return structure, but for a list endpoint this is acceptable. Somewhat complete for its 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?
Schema coverage is 100%, and the schema descriptions for limit and offset are already clear (defaults, ranges). The tool description adds no additional parameter information, so it meets 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 clearly states the tool lists signature requests (verb+resource), scoped to the configured Kamy account, with newest-first ordering. It distinguishes from sibling tools like create_signature_request and extract_document.
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 implicitly guides usage by noting that without a key it returns setup instructions, but it does not explicitly state when to use this tool versus alternatives like create_signature_request or get_api_key_instructions.
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?
Annotations already declare readOnlyHint=true, but the description adds crucial behavioral details: read-only operation that spends no quota, requires a Kamy API key with signatures:read scope, and without a key returns dashboard setup instructions. It also specifies the response shape { templates, total, limit, offset }.
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 that each earn their place: purpose + ordering, sibling differentiation, field-level details + referral to get_signature_template, usage as a preset ID, and auth/quota/return type. Front-loaded with the core function, 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?
Despite no output schema, the description fully covers return type, authentication, quota impact, and distinguishes from sibling list_templates. With simple pagination parameters (limit, offset) already well-documented in schema, the description provides all necessary context for an agent to correctly select and invoke 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?
Input schema has 100% coverage with clear descriptions for limit and offset. The description adds context about the returned data structure (fields included and excluded), pagination semantics (offset, limit implied), and how to use the results. This goes beyond schema to explain the meaning of the list output and its relationship to other tools.
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 lists reusable e-signature presets (saved field placements, etc.) ordered newest first. It distinguishes itself from list_templates, which is for the document catalog used by render_pdf. This provides a specific verb-resource pair and differentiates from siblings.
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 contrasts with list_templates, explains what fields are returned, directs users to get_signature_template for full details, and advises using the returned id in create_signature_request's signatureTemplateId. This gives clear when-to-use, what-not-to-expect, and integration guidance.
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 that these are public system PDF templates and require no authentication, providing additional 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 a single sentence that conveys all necessary information without any fluff. It is perfectly concise.
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 zero parameters, complete annotations, and no output schema, the description fully covers what the tool does and an important usage condition (no authentication). No additional information 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?
There are no parameters, so the description does not need to provide parameter details. Schema coverage is 100% (trivially), and the description is sufficient.
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 (templates), and the scope (Kamy's public system PDF templates). It effectively distinguishes from siblings like list_signature_requests by specifying 'PDF templates'.
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 includes 'No authentication required,' which provides useful context for when to use this tool. It does not explicitly mention when not to use it, but the sibling tools are clearly different in purpose.
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 mark readOnlyHint and destructiveHint, but the description adds substantial behavioral detail: snapshots are immutable, results are newest first, it spends no quota, requires a specific API scope, and describes the no-key error behavior. This goes well beyond the structured 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 serves a purpose: the first defines the output, the second links to related tools, the third clarifies what is excluded, the fourth scopes accessibility, and the last covers security and error response. It is dense but not bloated.
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 the essential usage context: output format, ordering, related tool alternatives, scope, authentication, and error behavior. It is fully self-contained.
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 templateId as 'Template UUID or slug', and the description reinforces this by noting it works on system and public templates as well as your own. This adds useful context beyond the schema, though the core parameter semantic is already well covered.
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 lists a template's immutable version snapshots, newest first, with a specific output shape. It also distinguishes itself from get_template_version by noting bodies are not included, 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?
It clearly explains the use case: the version numbers here are what publish_template and rollback_template accept. It also explicitly directs users to call get_template_version when they need a snapshot's body, and mentions the tool works on system and public templates, providing clear contextual 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 adds significant behavioral context beyond annotations: it states it is read-only and spends no quota (consistent with readOnlyHint=true), it specifies that signing secrets are never returned, and it describes the response fields including the meaning of lastStatus (HTTP code indicating broken endpoints). This level of detail helps the agent understand exactly what the tool does and does not expose.
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 long, each earning its place. The first sentence states the purpose and the key output (id). The second details the response fields and a critical insight about lastStatus. The third clarifies what is not returned and confirms read-only/no quota. No fluff, front-loaded, and well 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?
Given no parameters, rich annotations, and no output schema, the description is remarkably complete. It explains the purpose, the returned fields (url, events, enabled, lastDeliveryAt, lastStatus), the meaning of lastStatus, and the absence of signing secrets. The agent can fully understand the tool's behavior and output without needing additional documentation.
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, so schema coverage is 100% trivially. According to guidelines, the baseline is 4 for zero-parameter tools. The description adds no parameter information because there are none, and that 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 lists webhook endpoints on the account and provides the id needed to test one. It distinguishes from siblings like create_webhook (which returns signing secrets) and test_webhook (which uses the id). The verb 'list' and resource 'webhook endpoints' 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?
The description explains when to use this tool (to list webhooks, get the id to test one, check for broken endpoints via lastStatus). It also clarifies what it does not return (signing secrets, which are only from create_webhook). While it does not explicitly state 'do not use this to create/delete', the annotations and context make that clear. The guidance is strong but not exhaustive.
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?
The description adds significant behavioral context beyond the annotations: it states the source renders are left untouched (aligning with destructiveHint=false), mentions billing as one additional render, explains authentication requirements (API key with `render` scope), and describes the failure behavior for invalid IDs. 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, dense paragraph that front-loads the core action. Every sentence adds value—covers scope, constraints, prerequisites, behavior, return format, and billing. 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 tool's moderate complexity (2 parameters, one required array, no output schema), the description fully covers purpose, constraints, ordering, error handling, return format, authentication, and billing. It 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 coverage is 100%, so baseline is 3. The description reinforces the schema's details (order of IDs, failure condition, labeling) but does not add new semantic dimensions beyond what the parameter descriptions already provide. The description is consistent but not additive.
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 'concatenate' (merge), the resource 'existing renders', and the output 'single new PDF'. It distinguishes itself from sibling tools by explicitly noting it is 'the composition step after several render_pdf / convert_document / edit_pdf calls' and cannot merge arbitrary URLs or raw bytes.
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 (after rendering or conversion steps), what it cannot do (merge arbitrary URLs or raw bytes), prerequisites (IDs must belong to the account and point to completed renders), failure conditions, and API key requirements. It clearly differentiates from siblings like split_pdf or render_pdf.
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 indicate it is not read-only (readOnlyHint=false), and the description confirms it performs a cryptographic signature, which is a mutation. It also discloses the alternative outcome when no key is configured. No contradictions with annotations. Additional details about the signing standard (PAdES) are provided, but the impact on the original render is not explicitly stated.
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 only two sentences. The first sentence front-loads the main purpose and condition, and the second covers the fallback. 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?
Despite having 7 parameters and no output schema, the description does not explain what the tool returns (e.g., a signed PDF or a new document). It also lacks details on the signing process or prerequisites beyond the API key. Given the complexity of signing, more guidance is needed for the agent.
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 each parameter well. The tool description does not add extra parameter guidance beyond what the schema provides, meeting the baseline expectation.
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 ('cryptographically sign an existing render with PAdES') and the resource ('existing render'). It distinguishes this tool from siblings like verify_pdf_signature or create_signature_request by specifying the signing action and the condition of having a Kamy API key configured.
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 context for when to use the tool ('when a Kamy API key is configured') and what happens without it ('returns dashboard setup instructions'). However, it does not directly compare with sibling tools or state when not to use this tool, but the conditional guidance is helpful.
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?
The description is rich in behavioral detail: it explains that no signature request, email, or quota use occurs (read-only), lists all possible issue types (PAGE_OUT_OF_RANGE, OFF_PAGE_RIGHT, etc.), describes the fallback behavior when anchor text is not found, and details the return structure (page dimensions, per-field validation, resolved coordinates). It also discloses auth requirements and error handling, all of which go beyond the annotations (readOnlyHint) to provide comprehensive 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 given the complexity: every sentence earns its place, starting with the core purpose, then behavioral guarantees, input equivalence, return structure, issue list, prerequisites, and auth. It is front-loaded and well-organized with no redundancy or filler. Despite its length, it is efficiently structured for an AI agent 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?
With only two parameters (both documented in schema), no output schema, and fully covered annotations, the description is exceptionally complete. It covers prerequisites (render status, auth), error conditions (410, missing key), return content (page sizes, field coordinates, issues), the full issue taxonomy, anchor resolution details, and the tool's relationship to create_signature_request. Nothing essential is omitted.
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% coverage with descriptions, yet the description adds substantial value: it explains the equivalence to create_signature_request input, clarifies how anchor positioning works and the silent fallback behavior, describes the purpose of options and sourcePageWidth/Height, and details the semantic meaning of issues. This goes well beyond the schema's field-level 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 explicitly states the tool validates field placement layouts against a render's page geometry before any signature request is created, email sent, or quota spent. It clearly distinguishes itself from create_signature_request by emphasizing that no request is created, and it lists the same accepted field types, making the purpose specific and well-differentiated from siblings.
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 before create_signature_request ('anything that previews clean will send'), explains the source render must have 'success' status, and what happens if the PDF ages out (410 error, fix by re-rendering). It also states that issues detected here do not cause create_signature_request to fail, reinforcing its role as a pre-validation step.
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?
The description discloses the exact return shape { templateId, publishedVersion, publishedVersionId, latestVersion, publishedAt }, which is critical given no output schema. It also specifies the required auth scope (templates:write) and the fallback behavior without a key. This adds substantial behavioral context beyond the annotations (which only provide hints without details). No contradiction with annotations exists.
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, each earning its place: core purpose, no-version case, with-version case with sibling contrast, and identifier/return/auth details. No redundancy or fluff. Information is front-loaded and logically organized.
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 moderate complexity (two parameters, conditional behavior, no output schema), the description covers all essential aspects: purpose, usage modes, return format, auth requirements, and differentiation from siblings. The annotations (readOnlyHint=false, destructiveHint=false) are consistent, and the description fills any gaps left by the schema and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents both parameters. The description adds significant value by explaining the conditional semantics: omitting version triggers a draft snapshot, while supplying an existing version republishes it and leaves the draft untouched. It also clarifies that templateId accepts a UUID or slug, consistent with other routes. This goes well beyond 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 verb 'Make a template version live for rendering' and the resource 'template version'. It explains two distinct modes—snapshotting the current draft or republishing an existing version—and explicitly contrasts with the sibling tool rollback_template, which handles reverting bad releases with concurrency 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?
The description provides explicit when-to-use guidance for both parameter variants: omit version to ship an edit made with update_template, or supply an existing version to republish a known-good snapshot. It also gives a clear when-not-to-use directive: 'Reach for rollback_template instead when you are reverting a bad release', explaining why that tool is the correct alternative.
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 signal mutability (readOnlyHint: false, destructiveHint: false), so the description doesn't need to repeat that. The description adds behavioral context: the ledger is tamper-evident, records are hash-chained, and results include a verify_url. It also discloses a prerequisite (requires a Kamy API key). The only gap is no mention of rate limits or idempotency, but the behavioral coverage is 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 tightly written—three sentences, no filler. The first sentence delivers the core action and purpose, the second provides usage scenarios and chaining mechanics, and the third lists return fields and a prerequisite. 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?
Given the tool's moderate complexity (8 params, 2 required, no output schema), the description covers all essential aspects: what the tool does, when to use it, how to structure the chain, what it returns, and a prerequisite. The agent has enough context to invoke this correctly without referencing external documentation.
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 why certain parameters matter beyond their schema types: run_id is for chaining records, parent_sha256 explicitly links the chain, tool_call and tool_result should be verbatim. This is substantial added context that helps the agent use the tool correctly.
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 ('append'), the resource ('signed tool_call -> tool_result pair to a tamper-evident ledger'), and distinguishes the tool from siblings (e.g., get_provenance_chain for reading back, verify_attestation for verification). It explicitly says when to call it—after any consequential tool invocation—and lists non-obvious use cases (payment, email, write).
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 guidance: after any consequential tool invocation. It names a specific sibling (get_provenance_chain) for reading back results, which gives the agent an alternative. It also explains how to structure calls (stable run_id, parent_sha256 to link records), leaving no ambiguity.
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?
The description goes beyond annotations by detailing rate-limiting behavior (429 with Retry-After, silent skipping for envelope form), error responses (409 for non-pending states), and cumulative effect on auto-cadence. It also explains that the tool sends real emails to third parties, which isn't captured by annotations. The only gap is that it doesn't explicitly state whether the action is reversible or if it triggers any side effects beyond emailing, but given the existence of annotations (destructiveHint false, readOnlyHint false), this is still quite transparent.
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 information but is roughly 170 words, covering purpose, parameters, rate limits, error handling, and permissions. It's longer than ideal, but every sentence adds value—no fluff. Could be slightly trimmed for readability, but it earns a high score for efficiently packing actionable details.
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 no output schema, the description compensates by explaining what happens (email sent) and what responses to expect (429, 409, silent skip with skipped_reason). It covers permissions (requires signatures:write scope) and error cases. A small improvement would be noting the exact retry-after header format, but overall it feels complete for a nudge tool of moderate 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?
The input schema already covers both parameters with descriptions, achieving 100% coverage. The description adds context about what each parameter does (single vs. envelope-level nudge) and usage constraints (exactly one), which is useful but not transformative beyond the schema's own descriptions. 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 resends signature invitation emails, distinguishes between reminding a single signer (via signatureRequestId) versus an entire envelope (via envelopeId), and explicitly notes there is no separate envelope-reminder tool. This differentiation from sibling tools like create_signature_request or get_signature_request is strong.
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 each parameter ('supply exactly one; there is no separate envelope-reminder tool'), explains rate limits (429 REMIND_TOO_SOON, implicitly capped at one per hour), and clarifies edge cases: pending-only reminders, skipped sequential recipients, and the effect on the auto-cadence cap. It also warns that real emails are sent, providing essential context for safe invocation.
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?
Annotations are minimal (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds substantial behavioral context: non-blocking return, need to poll get_job, quota checked at job acceptance, 402 error on over-quota, and that the job result contains the finished render. This far exceeds what annotations alone provide, with no contradictions.
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 but is densely informative and front-loaded with the core behavior. Every sentence provides essential information: return format, when to use alternatives, polling, quota, and parameter equivalence. 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?
Given the tool's complexity (async, polling, quota, multiple alternatives), the description is remarkably complete. It explains the return value, polling mechanism, quota behavior, and even mentions that the finished render arrives on the job result. No output schema exists, but the description adequately covers what the agent needs to know.
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 stating that parameters are the same as render_pdf, explaining the 'name' field is echoed back, and clarifying the watermark behavior relative to the free-plan watermark. This extra context justifies 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 tool's core function: 'Queue one PDF render and return immediately with { jobId, status: "queued" } instead of waiting for the document.' It specifies the verb (queue), resource (PDF render), and asynchronous behavior. It also distinguishes itself from sibling tools like render_pdf and render_batch, 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 alternatives: 'Choose this over render_pdf when blocking is not acceptable... and poll get_job... Choose render_pdf when... and render_batch when...' It also addresses quota implications and failure modes, leaving no ambiguity about appropriate usage.
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 description discloses key behavioral traits beyond the annotations: it blocks, items render sequentially within a 300-second budget, partial batches are normal, the whole batch's quota is reserved up front (rejected with 402 if exceeded), and timed-out items return SERVICE_UNAVAILABLE without billing. This is thorough and consistent with the annotation (readOnlyHint=false, destructiveHint=false). No 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 about 6 sentences, front-loaded with the main purpose, and each sentence adds value (e.g., efficiency, blocking, quota, return format, error handling). It is compact yet informative. Minor redundancy could be trimmed, but overall very well-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?
Given the complexity (batch of 100, blocking, sequential, quota, partial failures) and no output schema, the description covers the return format, partial batch behavior, quota rejection, timeout handling, and retry advice. It does not detail the exact structure of a successful render result, but that is likely consistent with the sibling 'render_pdf' and the context is sufficient for an agent.
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% coverage, so each parameter is already described in the schema. The description adds high-level context (e.g., order matters, partial results) but does not significantly expand on individual parameter meanings 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 immediately states the core action: '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'), identifies the resource ('batch of PDFs'), and clearly distinguishes 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?
Explicit when-to-use guidance: 'Choose this over calling render_pdf in a loop whenever you have more than a couple of documents' for efficiency, and 'reach for render_async instead when you cannot' wait for blocking. Also advises checking quota before using: 'call get_account first if you are near the limit.' This fully covers 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.
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 are sparse (readOnlyHint false, destructiveHint false, openWorldHint false), so the description carries high burden. It clearly discloses mutation (counts against quota, requires render scope) and return structure (signed URL valid one hour, render id). Loses a point for not stating whether the data object is validated or what happens on invalid data beyond the template enum.
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 — starts with core purpose, then differential guidance, then constraints, then response format, then billing/scoping. No redundancy, no fluff. Front-loaded with critical sibling distinction.
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 moderate complexity (3 params, 1 enum, no output schema), the description fully covers the tool's operational context: supported templates, sibling relationship, auth requirements, quota behavior, API key setup instructions, and exact return fields. 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 description coverage is 100%, so baseline is 3. The description adds significant value by explaining the envelope (template/data) payload relationship to render_pdf, the signed URL lifetime, and quota impact, which are beyond the schema's parameter descriptions. Could be a 5 if it explained the data parameter default behavior more explicitly.
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 resource ('Word document') with specific output distinction from sibling render_pdf. It explicitly distinguishes itself as producing a .docx container for editable documents, making sibling differentiation strong.
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 guidance ('when the recipient has to EDIT the document') and when-not-to-use guidance ('use render_pdf for those' slugs not in the five listed). It also lists the exact set of supported templates and alternative for unsupported ones.
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?
The description fully discloses behavioral traits beyond the annotations: it states the tool is not read-only (mutation expected), not destructive, and not open-world. It adds important context about monthly quota counting, refusal of paid-tier templates on free plan, and the response behavior when no API key is provided (returns setup instructions). No contradiction with annotations since annotations are neutral (readOnlyHint=false, destructiveHint=false, openWorldHint=false) and the description aligns.
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 at about 6 sentences, with good front-loading of the core purpose. Each sentence adds distinct information. Minor reduction could be made by merging the quota and auth sentences, but it is well-structured and avoids 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 there is no output schema, the description compensates by specifying the return format ({ format: 'html', html, bytes }). The tool has 4 parameters with 100% schema coverage and moderate complexity (nested data object, mutual exclusion). The description covers the key behavioral aspects (quota, auth, error handling) but does not explain what 'template slug or UUID' means precisely or provide examples of valid template values. Slightly more detail on the response and error cases would push this to 5.
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% (all 4 parameters documented), so baseline is 3. The description adds value by explaining the relationship between template and html (mutually exclusive), introducing the concept of 'template slug or UUID', and clarifying the direction parameter's effect on lang/dir attributes. However, it does not elaborate on data parameter beyond what the schema says about Handlebars substitution, and nested objects are not explained further. This is strong but not exhaustive.
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 compiles a Kamy template or inline Handlebars source with a data payload to produce an HTML string. It explicitly distinguishes the tool from sibling render_pdf by noting what it does not do (no browser, no PDF, no file storage) and names the concrete use cases (piping into email providers, inspecting markup).
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 render_pdf ('Use render_pdf instead whenever the output has to be a paginated, printable artifact'), and specifies the constraint to supply exactly one of template or html. It also lists prerequisites (Kamy API key with render scope) and a condition (paid-tier system templates refused on free plan).
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 already mark the tool as not read-only, not open-world, and not destructive, which is consistent with a blocking render operation. The description goes well beyond annotations by disclosing the blocking/wait behavior, the one-hour signed URL expiration, the monthly quota impact (402 failure), and the authentication requirement (Kamy API key with `render` scope). This provides rich 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 a single, well-structured paragraph of about 120 words. Every sentence adds essential value: purpose, blocking behavior, alternatives, prerequisites, quota implications, and authentication requirements. There is no redundancy or filler, making it efficient for an AI agent 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 moderate complexity (3 parameters, nested objects, no output schema), the description is remarkably complete. It explains the blocking nature, return format, URL validity, sibling distinctions, prerequisite steps, quota limits, and auth requirements. No additional information seems necessary for an AI 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 67%, with `data` and `template` described in schema. The description adds no further parameter-level details (e.g., format values, data structure), but this is acceptable since the schema already provides basic descriptions. The description compensates by clarifying the tool's overall context, such as the `url` field meaning and quota impact, which indirectly aids 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 uses a specific verb ('Render') and resource ('PDF from a Kamy template and data'), and clearly distinguishes this tool from siblings like `render_async` and `render_batch`. It also explains the blocking behavior and the exact return structure, making the tool's 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 explicitly states when to use this tool ('default document tool'), when not to ('when waiting is not acceptable'), and names specific alternatives (`render_async`, `render_batch`). It also provides a precondition ('call get_template_schema first') and a quota check hint ('get_account tells you what is left'), offering comprehensive guidance for proper selection.
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?
Annotations already indicate readOnlyHint=false (mutation) and destructiveHint=false. Description goes beyond by disclosing return format (stored render with id, url, bytes, durationMs, format), signed URL expiration (one hour), quota counting, and authentication needs (Kamy API key with render scope). No contradictions.
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?
Five concise sentences, each providing essential information without redundancy. Front-loaded with the core action, immediately clarifies what it is not, and efficiently covers return value, quota, and authentication in minimal space.
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 the tool (4 parameters, nested objects, no output schema), the description is remarkably complete. It covers purpose, limitations, return format, quota, authentication, and integration with sibling tools. No gaps remain that would hinder an AI agent from correct 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 description coverage is 75%, and the description adds significant meaning by explaining that the slide layouts are fixed and content must be shaped into them. It also clarifies that the deck title is used as metadata and filename. While schema covers most parameters, the description adds crucial context about layout constraints and output format.
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 it builds a .pptx deck from a slide spec with five fixed layouts, and explicitly distinguishes itself from sibling tools like render_pdf, render_docx, and convert_document. It effectively differentiates from these alternatives.
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?
Description explicitly states when NOT to use (not a template renderer, not for free-form layout, not for file conversion) and guides the agent to use convert_document if a PDF is needed, and mentions quota counting and API key requirements. This provides clear usage context.
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 only mark readOnlyHint=false, but the description goes far beyond: it reveals the output format (id, url, bytes, durationMs, format, signed link valid for one hour), explains formula expansion in totalRow, notes that headers are always bold on tinted fill (no flag), warns about monthly quota, and describes what happens without an API key. This adds extensive behavioral context without contradicting any annotation.
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 packed into a few sentences, each earning its place: core purpose, structural details, sibling differentiation, output format, styling caveats, quota, and auth requirements. There is no repetition of schema information that is already clear, and no 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 the complexity (nested sheets, columns, totalRow) and the lack of an output schema, the description covers the key behavioral aspects: return structure, formula handling, styling, auth, quota, and next-step conversion. It omits error cases and synchronous behavior (implied by the return structure), but these are secondary. The schema already constrains row count and width limits, so the description doesn't need to repeat them.
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 explaining the formula-expansion behavior for totalRow (bare aggregators like 'SUM' transform into real formulas, '=' prefixes go verbatim), clarifying that title is the filename stem, and noting the header styling (bold, tinted fill) which relates to the columns parameter. These details improve the agent's understanding beyond the schema alone.
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 'Build an Excel (.xlsx) workbook from a sheet spec', using a specific verb and resource. It details the input structure (columns, rows, number formats, total row) and explicitly distinguishes itself from sibling tools render_pdf and render_docx, making the tool's 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?
The description provides clear guidance on when to use this tool versus render_pdf ('when the recipient will sort, filter or recompute') and render_docx ('when the content is tabular rather than prose'). It also mentions the API key requirement, quota impact, and a downstream option (convert_document). It does not explicitly state when not to use it, but the context is strong enough for an agent to decide.
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 flag destructiveHint=true, but the description adds critical behavioral context: it changes production renders, there is no undo beyond rolling forward, restoreDraft auto-snapshots the existing draft to preserve unsaved work, and missing API key leads to dashboard setup instructions. It also discloses the 409 VERSION_CONFLICT rejection, going beyond the annotations without contradicting them.
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 dense paragraph but every sentence adds pragmatic value—purpose, usage alternatives, destructive warnings, auth requirements, and concurrency behavior. It is not needlessly verbose, but it does pack many clauses into one block; could be slightly better structured with bullets, yet it remains efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 4 parameters, no output schema, and rich annotations, the description covers all essential dimensions: what it does, when to use it, safety/destructive impact, parameter nuances, and required permissions. Nothing important is missing, and the lack of an output schema is compensated by the detailed behavioral and param guidance.
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 is already detailed. The description adds extra value by explaining that templateId accepts UUID or slug and that expectedPublishedVersion is an 'optimistic fence' for concurrency control, plus the nuance that restoreDraft only snapshots when not byte-identical. This goes beyond the schema descriptions without repeating them, though the schema already does much of the heavy lifting.
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: 'Revert a template after a bad release: repoints published_version at the version you name, so every subsequent render immediately serves that snapshot again.' This clearly distinguishes it from the sibling publish_template by explaining the unique reversion mechanics and the expectedPublishedVersion parameter, making the 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?
Provides explicit guidance to prefer this tool over publish_template's version argument when reverting, and explains why: only this tool offers expectedPublishedVersion as an optimistic fence and can restore the working draft. It also clarifies when restoreDraft should be used (true/false behavior) and notes the auth requirement, covering when-to-use and exclusions.
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, destructiveHint=false. The description adds essential behavioral context: it is a heuristic aid, not a security boundary; it only analyzes passed-in text (no fetching or side effects); it requires a Kamy API key. This fully discloses the tool's operational scope and limitations beyond what annotations capture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-framed with a clear opening sentence that captures the core purpose. It is longer than strictly necessary but every sentence adds value—no filler. Slight room for trimming ('Heuristic pattern scan...' could be 'Scan...' but the detail aids 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 the tool has only 2 parameters with complete schema coverage, no output schema, and no nested objects, the description is complete enough. It explains when to use the tool, what it returns (risk levels and matched findings with excerpts), its limitations, authentication needs (API key), and that it's read-only.
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. The description does not need to repeat parameter details, as the schema adequately covers them. The description adds context about the tool's overall behavior that helps an agent understand how to use the parameters correctly.
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 verb ('scan'), resource ('tool description text'), and purpose ('for prompt-injection tells'). It explicitly lists what it detects (instructions addressed at the reading model, data-exfiltration hints, attempts to override system prompt or hide content), which distinguishes 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?
The description gives explicit when-to-use guidance ('Run it on descriptions from third-party MCP servers before you act on what they say') and clear when-not-to instructions ('a 'low' verdict is not evidence that a tool is safe... Do not treat any result here as clearance to trust an untrusted tool — keep your own judgement and human review in the loop'). It also sets expectations about the tool's limitations.
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?
Annotations are readOnlyHint=false and destructiveHint=false; the description confirms non-destructiveness ('The source render is left untouched') and describes the output structure ('Returns { renders: [...], count }'). No contradictions and adds meaningful behavioral 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?
Every sentence serves a purpose: purpose statement, usage example, edge-case behavior, return format, auth requirement. 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?
Despite no output schema, the description fully specifies the return format and how renders relate to other tools. Auth, error cases, and parameter behavior are covered. No gaps for a 2-param 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%, so baseline is 3. The description adds value by exemplifying multi-range usage ('halve a contract and peel off single pages') and clarifying the effect of omitting `to`, but these are largely redundant with schema descriptions. Slight improvement warrants 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 explicitly states the action ('Extract page ranges from one existing render into separate new PDFs'), identifies the resource (render), and distinguishes from a sibling tool ('the inverse of merge_pdfs'). This is 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?
Provides clear when-to-use guidance ('one call can both halve a contract and peel off single pages'), exclusion rules ('a range starting past the last page fails the entire call'), auth requirements ('Requires a Kamy API key with the `render` scope'), and fallback behavior ('without a key, returns dashboard setup instructions').
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 fully discloses behavioral traits: the tool sends a real HTTP POST, the response is asynchronous acceptance, and the ping is delivered regardless of subscription. Annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) are consistent with the description, and the description adds critical context about background delivery and response meaning.
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 with clear progression: action, purpose, behavior with follow-up, and nuance. Every sentence adds value, though it could be slightly more concise. It is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter, rich annotations, and no output schema, the description covers purpose, behavioral details, side effects, follow-up steps, and subscription nuance. It is complete for an agent to understand when and how to use 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?
With 100% schema description coverage and one parameter, the schema already documents webhook_id well. The description does not add new parameter semantics beyond what the schema provides, earning a baseline score 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 explicitly states the tool sends a real test.ping event to a registered webhook endpoint via an outbound HTTP POST, signed like a genuine delivery. It uses specific verbs and resources, and clearly distinguishes from sibling tools like create_webhook and list_webhooks by focusing on testing delivery.
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 'Use it to prove an endpoint is reachable and that signature verification works before relying on it.' It also provides follow-up guidance: wait seconds and call list_webhooks to check real outcome. It clarifies the ping is delivered regardless of subscription, helping agents decide 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.
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?
Beyond annotations, discloses that each record is hashed and signed at write time for non-repudiation, describes the return shape ({id, content_sha256, signature, recorded_at, verify_url}), and states auth requirements (API key with trace:record scope) and quota consumption. 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?
Succinct yet comprehensive paragraph. Front-loaded with core purpose, followed by unique trait (signing), usage guidance, parameter hint, return type, and auth/quota. Every sentence adds value without 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 11 parameters and no output schema, the description covers the essential: purpose, signing feature, use cases, return fields, auth, and quota. Combined with 100% schema documentation, it provides a complete picture for an AI agent to select 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 description coverage is 100%, so baseline is 3, but the description adds extra meaning: e.g., 'Set status flagged with status_detail on calls a human should revisit' for status parameter, and tags are 'filterable in trace_search'. Adds situational context 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 states the tool records one LLM call with specific fields into Kamy Trace, a signed retention ledger. It clearly differentiates from siblings like 'trace_search' and 'record_agent_action' by emphasizing the LLM call recording and cryptographic signing.
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 advises when to use the tool: 'Reach for it when model calls need a reviewable history: regulated workflows, customer-facing generations, anything you may have to explain months later.' Also explains setting status flagged for human review, and mentions required API key and quota.
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?
The description discloses behavioral traits beyond annotations: batch size limit (100), upfront quota check with 402 rejection on overage, all-or-nothing atomicity, return structure, required scope (`trace:record`), fallback behavior without key. Annotations only indicate non-readOnly and non-destructive; the description adds rich operational context. No contradictions.
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 (5 sentences) and well-structured: purpose first, then usage guidance, batch behavior, return format, and auth. Every sentence carries essential information with no fluff. Ideal front-loading of 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?
Given the tool's complexity (one parameter that is a complex array of objects) and the absence of an output schema, the description fully covers all necessary context: batch limits, quota behavior, return shape, auth requirements, and error handling. It is complete enough 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?
Input schema has 100% coverage with descriptions for all fields. The description adds meaning beyond the schema by explaining batch-level semantics (quota check, rejection, atomicity) and cross-referencing the shape of trace_record. It also describes the return format (not present in schema). This adds significant value, though individual parameter details are already covered by 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 purpose: 'Write up to 100 Kamy Trace records in one call.' It specifies the verb (write), resource (Kamy Trace records), and maximum batch size. It also distinguishes itself from the sibling tool trace_record by indicating when to use this batch version over the singular one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Reach for this over trace_record whenever you have more than a couple of buffered LLM calls to persist' with rationale (one auth, quota check, round trip). It also advises on handling quota exceedance ('split it or upgrade rather than retrying') and mentions auth requirements. This fully addresses when, why, and when not to use the tool.
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 mark readOnlyHint=true, destructiveHint=false, so the description mainly adds value by confirming read-only behavior ('Read-only') and specifying required auth scope (trace:read). It also discloses that response metadata includes next_cursor for paging but excludes bodies. 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?
Three well-structured sentences: one for what it does (filters, order, return fields), one for use cases, one for auth. Efficient and front-loaded. Slight redundancy in mentioning 'newest first' followed by cursor paging, but not problematic.
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 core functionality, pagination, what's excluded, and auth. No output schema exists, so description rightly explains return fields. Lacks explicit mention of default sort or cursor lifetime, but overall complete for a search 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 describes all 8 parameters with coverage 100%. The description adds no new parameter semantics but succinctly summarizes filter dimensions. Baseline 3 is appropriate since schema already does the job.
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 it queries Kamy Trace records, explicitly lists filter dimensions (feature, status, provider, tag, time window), specifies ordering (newest first), and differentiates it from sibling tools like trace_record (individual record) and scan_tool_description by focusing on search and filtering.
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 example questions ('how many flagged calls last week?') and a practical use case ('locate a specific record id before opening it in the dashboard'). Clearly states what it does not return (stored prompt and output bodies), guiding agents away from misuse.
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 correctly set readOnlyHint=false, destructiveHint=false. The description adds critical behavioral context: the tool only modifies the draft, changes are invisible until published if a published_version exists, and it clarifies error conditions (403 for system templates or cross-account). The description could add that the tool does not validate the schema or HTML for correctness, but overall it provides strong 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 a single dense paragraph. It packs essential context efficiently but could be split into bullet points or shorter sentences for easier scanning. Every sentence provides value, but readability suffers slightly from the dense format.
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, no output schema, and the complexity of draft/publish semantics, the description covers the most critical aspects: what the tool does, its limitations (draft-only), authentication requirements, and error conditions. It could mention whether the tool returns the updated template or just success, but overall it's quite 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 50% (4 of 8 parameters have descriptions). The description fills gaps by listing which fields can be edited (name, html, css, schema, tags, visibility) and noting the UUID/slug addressing. It clarifies that only passed fields are changed. However, it doesn't elaborate on the format of the 'tags' array or the 'schema' object structure beyond what the schema provides.
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 identifies the tool as editing a custom template's DRAFT fields (name, html, css, schema, tags, visibility) and distinguishes it from operations that affect published content. It explicitly contrasts with render_pdf and publish_template, 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?
The description provides explicit guidance on when to use this tool versus alternatives: it notes that edits won't affect published renders unless publish_template is called, explains when a 403 is returned (system templates or other accounts), and clarifies that the tool requires a specific API key scope. This helps the agent avoid misuse.
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?
Beyond annotations (which are minimal), the description reveals multiple behavioral traits: the dual upload mechanism, size limits, time constraint, return value shapes for both scenarios, MIME restriction enforcement, and authentication requirements. This fully informs the agent about the tool's non-obvious behaviors and 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 a single, dense paragraph, but every sentence adds essential information without redundancy. It front-loads the core purpose (storing assets and returning references). A slight improvement would be structuring into separate sentences or bullets, but it remains efficient and scannable.
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 specifies the return object shape for both modes (`{ id, assetRef, bytes, uploaded: true }` and `{ uploadUrl, uploadMethod, uploadHeaders, expiresAt, uploaded: false }`). It covers auth, size caps, timeouts, MIME restrictions, and integration with other tools (render_pdf/render_html). The description leaves no major information gaps for an agent to safely and correctly invoke 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?
The input schema covers all 4 parameters with descriptions (coverage 100%). The description adds extra semantics: it explains that `contentBase64` triggers immediate upload vs. deferred, that `sizeBytes` is auto-computed when `contentBase64` is present, and that `contentType` must be from the enum. This enriches the schema's baseline by providing usage context and dependencies between parameters.
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 stores an asset (image, font, PDF) in the account's asset bucket and returns a `kamy://asset/<id>` reference. It specifies the verb 'store', the resource type, and the output, and distinguishes itself from sibling tools by being the only upload-focused 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 explicitly explains two usage modes: supplying contentBase64 for inline uploads (capped at 5 MB) or omitting it to receive a pre-signed URL for large files (up to 100 MB, 15-minute window). It also states the acceptable MIME types, the required API key scope (`uploads:write`), and implies when this tool should be used (for assets needed in render_pdf/render_html templates). This provides clear situational guidance.
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?
Annotations already indicate readOnly and non-destructive. Description adds that it's a dry-run, no quota use, returns self-healing errors. No contradictions.
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 clear sentences: first explains operation and return, second mentions API key requirement. 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?
No output schema, but description explains what is returned (per-field self-healing errors). Covers all relevant aspects for a validation 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%, so baseline 3. The description mentions 'Template slug (e.g. invoice) or template UUID' which already appears in schema. Does not add significant new meaning beyond 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 it dry-runs a render payload against a template schema without producing a PDF or using quota. Distinguishes from sibling render_pdf by specifying 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 says to use before render_pdf to fix data, implying when to use. Provides context on what it does, but does not explicitly state when not to use or list other alternatives.
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 declare readOnlyHint=true, destructiveHint=false, establishing it as a safe read operation. The description adds valuable context: explains the return value structure for matches and the nuanced meaning of a false result (no attestation vs. tampering), and discloses that no API key is required. This exceeds what annotations provide, though it doesn't mention potential rate limits or error handling.
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 6 sentences. It is front-loaded with the core purpose and usage hint. While every sentence is informative, some minor redundancy ('the tool that actually returns a verdict') could be trimmed. Still, it is efficient and well-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?
Given the tool's simplicity (1 parameter, no output schema, read-only annotations), the description covers the essential aspects: input type, return value for matches and misses, authentication requirements, and usage guidance. It does not detail error responses or rate limits, but for a query tool, this is reasonably 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?
The schema already documents the hash parameter with 100% coverage (pattern, type, description). The description adds further meaning: 'Hash the bytes you actually hold — if they were modified after attestation, the digest won't match any record and `verified` comes back false.' This clarifies the consequence of incorrect input, adding value beyond the schema's 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 — the tool that actually returns a verdict.' It uses a specific verb (verify) and resource (attestation by digest) and distinguishes itself from the sibling tool verify_pdf_signature by explicitly noting the difference in input type.
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: '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.' This clearly states the input requirement and points to an alternative tool for PDFs, helping the agent decide when to invoke this tool versus verify_pdf_signature.
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?
Despite having annotations, the description adds important behavioral nuance: the meaning of each returned status ('new', 'unchanged', 'mutated'), that 'unchanged' is not a trust verdict, and that a first-ever 'new' result only establishes a baseline. It also discloses the API key requirement. This goes well beyond the annotations without contradicting them.
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 dense paragraph but every sentence earns its place: it covers purpose, usage, return format, semantic caveats, and auth. It is front-loaded with the core purpose. It is slightly longer than strictly needed, but no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description fully explains the return value: status values, per-tool changes list with previous and current hashes. It also covers input modes, auth requirement, and nuance about trust. This is complete enough 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 coverage is 100% and each parameter already has a descriptive comment. The tool description reinforces the mutual exclusivity ('Supply either server_url or manifest') and clarifies that server_url is fetched server-side while manifest is for local/private servers. This adds meaningful context beyond the schema, though the schema already carried most of the burden.
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: 'Detect when an MCP server changes its tool manifest after you adopted it.' It immediately distinguishes this from sibling tools by focusing on the 'rug pull' scenario and post-adoption manifest integrity, 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?
It gives clear usage context for each input path: '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).' This explicitly tells the agent when to choose each parameter. However, it does not name alternative sibling tools or state when not to use this tool, so it falls 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.
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?
Beyond the annotations (readOnlyHint, destructiveHint), the description discloses significant behavioral details: the hashing is purely local in memory, no API call is made, nothing is stored or forwarded, and no key is needed. It also clarifies that the tool returns a hash and URL, not a verdict, which is critical for the agent to understand the tool’s capability boundary.
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 (5-6 sentences) and front-loaded with the primary purpose. Every sentence adds distinct value: local execution, no storage, no verdict, sibling differentiation, usage guidance. 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?
Given the low complexity (1 parameter, no output schema, no enums) and the presence of rich annotations, the description covers all necessary aspects: what the tool does, what it returns (sha256 and URL), its limitations (no verdict), and exactly when an agent should choose this tool versus verify_attestation. The description is fully self-contained.
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 description coverage, the baseline is 3, but the description adds valuable context: it explains that pdfBase64 is the file the agent 'is holding', reiterates the in-memory hashing, and describes the output (sha256 and verify URL) even though no output schema exists. This compensates for the missing structured output definition.
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 verb and resource: 'Turn PDF bytes ... into their SHA-256 digest and the matching kamy.dev/verify/{sha256} page URL.' It also distinguishes itself from the sibling verify_attestation by labeling itself as 'the first half of a check' and noting it returns no verdict.
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 guidance: 'Use this whenever you have the file itself; use verify_attestation directly when someone has already given you a digest.' It also explains the tool's role as the first half of a two-step process, giving the agent clear context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claiming 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 or an account that owns the GitHub organization, then choose Claim with GitHub.
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!
Add one secure layer between your agents and this server.
Each tool has a clearly distinct purpose with detailed descriptions that differentiate similar tools (e.g., render_pdf vs render_async vs render_batch, create_signature_request vs create_envelope). No two tools overlap in a way that would cause confusion.
All tool names follow a consistent lower_snake_case verb_noun pattern (e.g., attest_artifact, convert_document, list_renders). No mixing of conventions or ambiguous verb choices.
47 tools is high but reflects the broad scope of the platform (document generation, signing, auditing, scheduling, webhooks, verification). Some informational tools could be merged, but the count is still reasonable for the domain.
The tool set covers the core document lifecycle well but has notable gaps: no tool to delete renders, no tool to void/cancel signature requests, and no CRUD for templates (only list and schema). The inability to pause schedules via MCP is also a gap.