The PolicyForge MCP Server integrates AI coding tools with legal policy workflows to generate, manage, audit, and integrate policies from your codebase.
Generate policies: Create privacy policies, terms of service, cookie policies, refund policies, EULAs, disclaimers, and HIPAA Business Associate Agreements (Pro plan required). Regenerate policies with updated context while retaining the same hosted URL.
Manage and version policies: List, get, update (hand-edit without consuming quota), and delete policies. View version history and restore any previous version (restores are also versioned).
Audit compliance and detect drift: Perform gap analysis comparing codebase practices against policy disclosures. Check policy freshness by detecting drift between the current codebase and the manifest stored at generation time. Both are free.
Discover and integrate: Obtain a disclosure checklist mapping codebase elements (dependencies, scripts, cookies, hosts) to required disclosures. Get copy-paste integration guides for Next.js, React, HTML, or WordPress. List supported policy types, business types, and jurisdictions. Check your subscription tier and remaining quota.
Codebase-aware: The server scans your codebase to auto-populate policy fields. Authenticate via browser OAuth or API key; also supports local npx execution.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@PolicyForge MCP Server generate a GDPR & CCPA privacy policy for this app"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Generate legal policies — privacy policies, terms of service, cookie policies, refund policies, EULAs, disclaimers, and HIPAA Business Associate Agreements — directly from your AI coding tools (Claude Code, Cursor, Windsurf, Claude Desktop) via the Model Context Protocol.
Ask your agent "generate a GDPR + CCPA privacy policy for this app" and it fills the details from your codebase, calls PolicyForge, and drops the policy straight into your project.
Try it free: compliance audits (audit_compliance), drift checks
(check_policy_freshness), and the scan rubric (get_disclosure_checklist)
are unlimited and never touch your quota — start with
"audit our compliance — does the privacy policy cover everything this code
actually does?". And the first time your account connects through MCP it gets
3 bonus policy generations on top of the free 2/month — enough to generate
privacy, terms, and cookie policies for a new project in one conversation.
Pick the row that matches your client. If you're unsure, start with A.
How you sign in | Best for | |
A. Remote + OAuth | Browser sign-in, no key to copy | Clients that support OAuth (Claude, ChatGPT) |
B. Remote + API key |
| Any client that can send a header |
C. Local (npx) |
| Running the server as a local process |
All three expose the same tools. A and B need nothing installed.
No key to copy, no config file to edit. You'll need a PolicyForge account first — https://policyforge.co, free, no card.
1. Add the server. The -s user makes it available in every project rather
than only the directory you ran this in:
claude mcp add -s user --transport http policyforge https://policyforge.co/api/mcpNote there is no --header. Omitting it is what makes the client use OAuth.
2. Restart your client. MCP config is read at startup, so a session that was already running won't see the new server.
3. Authenticate. Run /mcp, select policyforge, and press Enter:
policyforge · △ needs authenticationYour browser opens, you sign in and approve, and the client stores the token
itself. You should land back at /mcp showing ✔ connected · 15 tools.
To confirm from the other side, a key named MCP · <your client> appears at
https://policyforge.co/api-dashboard — that's the grant, and deleting it
revokes access.
Other clients differ in step 3: some prompt on first tool use rather than offering an explicit authenticate action.
For clients that don't do OAuth yet. Create a key at https://policyforge.co/api-dashboard, then:
claude mcp add --transport http policyforge https://policyforge.co/api/mcp \
--header "Authorization: Bearer pf_your_key_here"For clients with URL-based MCP config (Cursor, Windsurf, and others):
{
"mcpServers": {
"policyforge": {
"url": "https://policyforge.co/api/mcp",
"headers": { "Authorization": "Bearer pf_your_key_here" }
}
}
}Prefer a local process? The server runs via npx — nothing to install
globally. Uses an API key from the environment, which is what the MCP spec
recommends for stdio transports.
claude mcp add policyforge \
--env POLICYFORGE_API_KEY=your_key_here \
-- npx -y @policyforge/mcp@latestAdd to your MCP config (.cursor/mcp.json, claude_desktop_config.json, etc.):
{
"mcpServers": {
"policyforge": {
"command": "npx",
"args": ["-y", "@policyforge/mcp@latest"],
"env": {
"POLICYFORGE_API_KEY": "your_key_here"
}
}
}
}On Windows, some clients need the command wrapped: set
"command": "cmd"and"args": ["/c", "npx", "-y", "@policyforge/mcp@latest"].
See https://policyforge.co/mcp for one-click installs (Cursor/VS Code) and per-client instructions — with your API key pre-filled when signed in.
Related MCP server: mcp-shiplegal
401 — if you connected with OAuth, the authorization was revoked or
expired: reconnect and approve again. If you used an API key, it was deleted,
disabled, or mistyped (keys start with pf_) — rotate or create one at
https://policyforge.co/api-dashboard and restart the client.
402 — generation quota exhausted. Free tier: 2 generations per calendar
month, plus a one-time bonus of 3 extra generations on first MCP connect.
Only generate_policy/regenerate_policy consume quota — audits and drift
checks are free; ask your agent to run get_usage to see what's left.
429 — request rate limit (free tier: 10/minute, 100/day); the response
includes retry_after.
Server not listed in /mcp — either the session started before you added
it (restart the client; config is read at startup), or it was added to a
different project scope. claude mcp add -s user … makes it available
everywhere.
Tools missing — restart the client after config changes; on Windows use
the cmd wrapper above.
"The redirect URI is not registered for this application" — the client is using a callback URL we haven't seen. Loopback callbacks work on any port (per RFC 8252), so this should be rare; report the exact URI and it can be supported.
More detail: https://policyforge.co/mcp#troubleshooting
Tool | What it does |
| Generate a policy and return its Markdown content + hosted URL. Consumes one policy from your quota. |
| Generate a HIPAA Business Associate Agreement between a covered entity and a vendor handling PHI. Built from the clauses required by 45 CFR 164.504(e) and validated clause by clause. Pro plan; never publicly hosted. Consumes one policy from your quota. |
| Re-run the AI engine with changed business context — same ID and hosted URL, previous content saved as a version. |
| Hand-edit a policy in place — same ID and hosted URL, so published links keep working. |
| Gap analysis: compare what the code does (your scanned manifest) with what a policy discloses. |
| Drift detection: diff the current codebase scan against the manifest stored at generation time. |
| Version history — a snapshot is saved before every update, regeneration, or restore. |
| Roll a policy back to any previous version (itself reversible). |
| List policies on your account (filter by type/status, paginate). |
| Fetch a single policy by ID, including full content. |
| Permanently delete a policy (its hosted URL stops working). |
| Check your tier and remaining generation quota before generating. |
| The codebase-scan rubric: which SDKs/patterns require disclosure and how findings map to |
| Copy-paste embed/link instructions for Next.js, React, plain HTML, or WordPress. |
| List supported policy types, business types, and jurisdictions. |
Your agent can read your project — so policies come from what the code actually does, not what you remember it doing:
get_disclosure_checklist → agent scans dependencies, script tags, cookie
writes, and outbound hosts against the rubric, and builds a stack
manifest of what it found
generate_policy with the detected context + stack_manifest (stored
server-side for drift detection)
get_integration_guide → agent wires the hosted policy into your footer
Later, after the stack changes: check_policy_freshness reports the drift,
audit_compliance shows the concrete gaps, and regenerate_policy fixes
them — same hosted URL, no broken links, previous version restorable
generate_policy inputsRequired: type, business_type, jurisdiction, company_name, contact_email
type — privacy_policy · terms_of_service · cookie_policy · refund_policy · eula · disclaimer
business_type — e-commerce · saas · healthcare · education · financial · fintech · real-estate · non-profit · consulting · media · mobile_app · other
jurisdiction — one or more of gdpr ccpa pipeda lgpd us eu ca uk au br global (comma-separate to combine, e.g. gdpr,ccpa)
Optional context (improves output): website_url, service_description,
data_collection[], third_party_integrations[], data_retention,
user_accounts, payments, marketing, analytics, cookies,
children_data, sells_data, target_audience[], security_measures[],
governing_law, physical_address, dpo_email, consent_tracking,
hosting_enabled.
generate_baa inputsA Business Associate Agreement is a contract between two named parties, not a published policy, so it takes its own tool and its own fields. Pro plan.
Required: acknowledge_contract (must be true), baa_direction,
company_name, contact_email, both parties' legal names and addresses,
baa_effective_date (YYYY-MM-DD), baa_services_description,
baa_phi_types[], baa_permitted_uses[], baa_governing_law_state.
baa_direction — covered_entity_to_vendor (you are the practice issuing
the agreement) or business_associate_to_client (you are the vendor
offering it to a healthcare client)
baa_phi_types[] — categories of PHI involved. Including
"Substance use treatment records (42 CFR Part 2)" adds a Part 2 addendum
baa_permitted_uses[] — anything not listed here is not permitted by the
agreement (45 CFR 164.504(e)(2)(i))
Optional: baa_electronic_phi (default true),
baa_uses_subcontractors (default false), baa_term_type,
baa_term_end_date, baa_breach_notification_days (1–60, default 30),
baa_return_or_destroy, baa_include_indemnification,
baa_include_insurance, baa_insurance_amount.
Every generated agreement is checked against the 15 clauses 45 CFR 164.504(e) requires before it is returned; an incomplete draft is refused rather than handed back. The result is still a draft for counsel to review, and it is never published at a public URL.
Only needed for the local (npx) transport. Remote connections authenticate
over OAuth or an Authorization header instead.
Env var | Required | Default | Purpose |
| yes (local only) | — | Your PolicyForge API key. |
| no |
| Override the API base URL (self-host/testing). |
This server is a thin wrapper over the PolicyForge public REST API (/api/v1).
Every tool maps to one authenticated HTTP request, so quota, rate limiting, and
policy generation stay authoritative on the PolicyForge server — the MCP layer
holds no secrets beyond your API key and no business logic of its own.
MIT
Compliance gap analysis: submit the stack manifest you built by scanning the codebase (see get_disclosure_checklist), optionally with a policy_id to audit against. PolicyForge compares what the code does with what the policy discloses and returns missing disclosures, overstated claims, missing policy types, and recommendations. Without a policy_id it audits the manifest alone (which policies are needed and what they must cover). Does not consume generation quota.
| Name | Required | Description | Default |
|---|---|---|---|
| manifest | Yes | The detected-stack summary from your codebase scan, e.g. {"analytics":["posthog"],"payments":["stripe"],"ai_features":["openai"],"cookies":["session","_ph_*"],"jurisdiction_signals":["EU locales"],"user_data_collected":["email","usage_events"]}. | |
| policy_id | No | Policy (UUID) to audit the manifest against. Omit to audit the manifest alone. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds meaningful context: it clarifies that the tool is read-only, does not consume generation quota, and returns specific outputs (missing disclosures, overstated claims, etc.). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph of four sentences. Each sentence serves a purpose: stating the action, explaining the input, detailing the output based on mode, and adding a non-obvious behavioral note. 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's complexity (two parameters, nested object, no output schema), the description covers all necessary aspects: prerequisite tool, two modes, return values, and a behavioral trait (quota). It references a sibling tool and provides enough detail for 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?
Input schema has 100% coverage with descriptions for both parameters. The description adds value by explaining the origin of the manifest (from codebase scan) and the effect of omitting policy_id. This goes beyond the schema, though the schema already provides solid 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 clearly states the verb 'submit' and resource 'compliance gap analysis', and distinguishes from sibling tools like get_disclosure_checklist and generate_policy. It specifies the input (stack manifest) and the two modes (with/without policy_id), 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?
The description provides explicit context: use after scanning codebase with get_disclosure_checklist. It explains both use cases (with and without policy_id) and notes that it doesn't consume generation quota. However, it doesn't explicitly state when to avoid using this tool (e.g., for policy generation or listing), leaving a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Drift detection: scan the codebase now (get_disclosure_checklist), build the current stack manifest, and compare it against the manifest stored when the policy was last generated/regenerated. Reports what changed in the stack so you know whether the policy still matches the code. Runs locally on the two manifests — no AI call, no quota.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The policy ID (UUID) to check. | |
| current_manifest | Yes | The stack manifest from your fresh codebase scan. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds valuable behavioral context: 'Runs locally on the two manifests — no AI call, no quota,' and explains the comparison process, going 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 extremely concise: two sentences, no wasted words. It front-loads the key purpose ('Drift detection') and efficiently communicates the workflow and constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main behavior and outcome, though there is no output schema to detail the report format. It references a sibling tool (get_disclosure_checklist), which is helpful. For a simple drift detection tool, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds context by mentioning 'scan the codebase now (get_disclosure_checklist)' which hints at how to obtain the current_manifest, adding value 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 action: 'scan the codebase now... build the current stack manifest, and compare it against the manifest stored... Reports what changed...' It specifies the resource (policy freshness/drift) and distinguishes from siblings by noting it runs locally with no AI call or quota.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use: 'Drift detection... so you know whether the policy still matches the code.' It does not explicitly state when not to use or name alternatives, but the sibling tool list and context make the use case clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a policy. The hosted URL and any embeds of it stop working immediately, and this cannot be undone. Confirm with the user before deleting anything they may have linked from their site.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The policy ID (UUID) to delete. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant context beyond annotations: deletion is permanent, URL and embeds stop immediately, cannot be undone, and requires user confirmation. This complements the destructiveHint=true annotation effectively.
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. The first sentence states the core action and consequence; the second provides a critical usage guideline. Front-loaded 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 one-parameter tool with no output schema, the description covers the purpose, effect, and caution. Could optionally mention the return value or confirmation response, but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add any additional meaning to the id parameter 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 starts with 'Permanently delete a policy', specifying the verb and resource clearly. It distinguishes from sibling tools like update_policy, which modifies rather than deletes.
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 guidance on when to use (to permanently delete a policy) and explicitly advises confirmation with the user before deleting linked content. However, it does not explicitly state when not to use or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a HIPAA Business Associate Agreement (BAA) between a covered entity and a vendor that handles Protected Health Information. Built from the clauses required by 45 CFR 164.504(e) and validated clause by clause before it is returned.
Use this instead of generate_policy for BAAs — a BAA is a binding two-party contract, not a published policy, so it needs both parties' legal names and addresses and is never hosted at a public URL.
Ask the user for the party details, effective date, and governing law: these are negotiated facts you cannot read from source code. Requires a Pro plan. The result is a draft for counsel to review, not executed legal advice.
| Name | Required | Description | Default |
|---|---|---|---|
| company_name | Yes | Legal name of the user's own company. | |
| baa_direction | Yes | covered_entity_to_vendor (you are the practice) or business_associate_to_client (you are the vendor). | |
| baa_phi_types | Yes | Categories of PHI involved. Including "Substance use treatment records (42 CFR Part 2)" adds a Part 2 addendum. | |
| baa_term_type | No | Default tied_to_services (runs with the underlying services agreement). | |
| contact_email | Yes | Contact email for the agreement. | |
| baa_term_end_date | No | YYYY-MM-DD — required when baa_term_type is fixed_term. | |
| baa_effective_date | Yes | YYYY-MM-DD — the date the parties agree on, not today. | |
| baa_electronic_phi | No | Default true — triggers the HIPAA Security Rule safeguard obligations. | |
| baa_permitted_uses | Yes | Permitted uses and disclosures per 45 CFR 164.504(e)(2)(i). Anything not listed is not permitted. | |
| acknowledge_contract | Yes | Must be true — a Business Associate Agreement is a binding contract, not legal advice, and should be reviewed by counsel before signing. | |
| baa_insurance_amount | No | Minimum cyber liability coverage, e.g. "$1,000,000 per occurrence". | |
| baa_include_insurance | No | Pair with baa_insurance_amount. | |
| baa_return_or_destroy | No | What happens to PHI at termination. | |
| baa_covered_entity_name | Yes | Legal name of the covered entity. | |
| baa_governing_law_state | Yes | Governing law state. Stricter state health privacy law is layered on top of HIPAA. | |
| baa_uses_subcontractors | No | Default false — true adds the subcontractor flow-down clause. | |
| baa_services_description | Yes | The services that bring the associate into contact with PHI. | |
| baa_covered_entity_address | Yes | Address of the covered entity. | |
| baa_business_associate_name | Yes | Legal name of the business associate. | |
| baa_include_indemnification | No | Indemnification running from associate to covered entity. | |
| baa_breach_notification_days | No | Days to report a breach after discovery. Default 30. 60 is the outer limit under 45 CFR 164.410. | |
| baa_business_associate_address | Yes | Address of the business associate. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond annotations: it generates and validates a BAA clause by clause, emphasizes it's a binding contract, and clarifies it is not legal advice. No contradiction with annotations. It could explicitly state that it creates a new document, but the write nature is clear from the 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?
Three well-structured paragraphs: purpose/feature, differentiation from sibling, and usage guidance. Every sentence adds value without redundancy. Efficient and clear.
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 explains the outcome (draft for counsel review) and covers required inputs and constraints comprehensively. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds general guidance about which parameters are negotiated facts, but does not provide deeper semantics than the schema descriptions for individual parameters. Adequate but no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a HIPAA BAA between a covered entity and a vendor, specifies the regulatory basis (45 CFR 164.504(e)), and explicitly distinguishes it from generate_policy by noting it's a binding two-party contract, not a published policy.
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 'Use this instead of generate_policy for BAAs' with reasoning, and advises the AI to ask the user for negotiated facts like party details, effective date, and governing law. Also notes the Pro plan requirement and that the result is a draft for counsel review.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a legal policy (privacy policy, terms of service, cookie policy, refund policy, EULA, or disclaimer) for a business and return its Markdown content plus a hosted URL. Consumes one policy from the account's quota. IMPORTANT: if you are working inside the user's project, call get_disclosure_checklist and scan the codebase FIRST (dependencies, script tags, cookie writes, outbound hosts), then fill the optional fields below from what the code actually does — do not ask the user for facts you can read from source. Only ask for what code cannot tell you: legal company name, contact email, physical address, governing law.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | The kind of policy to generate. | |
| cookies | No | Does it use cookies? Defaults to true for most websites. | |
| payments | No | Does it process payments? | |
| analytics | No | Does it use analytics? | |
| dpo_email | No | Data Protection Officer email, if any. Also sets hasDPO. | |
| marketing | No | Does it send marketing communications? | |
| sells_data | No | Does it sell or share personal data? | |
| website_url | No | Company website URL. | |
| company_name | Yes | Legal/display name of the company. | |
| jurisdiction | Yes | Target legal framework(s). One or more of: gdpr, ccpa, pipeda, lgpd, us, eu, ca, uk, au, br, global, Europe, Canada, United Kingdom, Australia, Brazil, India, Singapore, Japan, Mexico. Combine multiple comma-separated, e.g. "gdpr,ccpa". Country/region names are case-sensitive as listed. | |
| business_type | Yes | The company's business category. | |
| children_data | No | Does it knowingly collect data from children? | |
| contact_email | Yes | Public contact email for legal inquiries. | |
| governing_law | No | Governing law jurisdiction, e.g. "State of California, USA". | |
| user_accounts | No | Does the product have user accounts? | |
| data_retention | No | How long data is kept, e.g. "24 months". | |
| stack_manifest | No | Structured summary of the stack you detected while scanning the codebase (see get_disclosure_checklist), e.g. {"analytics":["posthog"],"payments":["stripe"],"auth":["supabase"],"ai_features":["openai"],"cookies":["session"],"jurisdiction_signals":["EU locales"]}. Stored server-side so check_policy_freshness can detect drift when the stack changes later. Provide it whenever you scanned the project. | |
| data_collection | No | Categories of personal data collected, e.g. ["email","name","usage"]. | |
| hosting_enabled | No | Host the policy at a public policyforge.co URL (default true). | |
| target_audience | No | Audience segments, e.g. ["businesses","consumers"]. | |
| consent_tracking | No | Enable the "I agree" consent banner on the hosted page (default false). | |
| physical_address | No | Company physical address. | |
| security_measures | No | Security controls, e.g. ["encryption at rest","MFA"]. | |
| table_of_contents | No | Add a linked table of contents to the generated document. Requires a Pro plan. | |
| service_description | No | Short description of what the product or service does. | |
| third_party_integrations | No | Third-party processors, e.g. ["Stripe","Google Analytics"]. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only (readOnlyHint=false) operation, so the description adds value by disclosing that it 'Consumes one policy from the account's quota' and that it returns both Markdown and a hosted URL. It also mentions hosting defaults and the workflow with get_disclosure_checklist, which are useful behavioral details 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 moderately long but every sentence is purposeful: it lists policy types, states the return value, alerts about quota consumption, and provides a crucial pre-step (get_disclosure_checklist). The key information is front-loaded, and the structure is logical. It is not overly verbose for a tool with 26 parameters.
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 (26 params, nested stack_manifest) and the absence of an output schema, the description covers the essential context: what it returns, the quota side effect, and the required workflow when in a project. It doesn't explain all parameters (schema does), but it gives enough high-level context for correct invocation. Some minor gaps remain (e.g., error conditions, but these are not critical).
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 workflow-level guidance (scan the codebase and fill optional fields from source) and clarifies which fields must come from the user (company name, contact email, physical address, governing law). However, it does not add significant per-parameter meaning beyond the schema, which already describes each field in detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: generate a legal policy (privacy, terms, etc.) and return Markdown content plus a hosted URL. It specifies the verb, resource, and outcome, and distinguishes from sibling tools like generate_baa (which handles BAAs) and update_policy/regenerate_policy (which modify existing policies).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: when working inside a user's project, call get_disclosure_checklist first and scan the codebase, and only ask the user for facts code cannot reveal. It also warns about quota consumption. However, it does not explicitly compare with sibling tools (e.g., when to use update_policy instead), though the generation-specific behavior is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the rubric for scanning a codebase before generating or updating policies: which SDKs, scripts, and patterns legally require disclosure, and how each finding maps to generate_policy's fields. Call this before generate_policy when working inside the user's project — policies derived from the actual code beat policies from memory.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description adds meaningful context: the tool retrieves a static rubric used for policy preparation, implying no side effects. It also explains the mapping to generate_policy fields, enhancing transparency 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?
Two sentences with no repetition or filler. The first sentence conveys purpose and content, the second gives usage guidance. Efficiently front-loaded with essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description is sufficient for an agent to select and invoke the tool correctly. It explains what the rubric contains, when to call it, and how it relates to generate_policy, covering all necessary context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the input schema is fully covered. The description does not need to add parameter details but adds value by explaining the tool's output and usage. Baseline 4 for 0 parameters 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 retrieves a rubric for scanning a codebase before generating or updating policies, and specifies the content: which SDKs, scripts, and patterns require disclosure and how they map to generate_policy fields. This distinguishes it from siblings like generate_policy or list_policies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises calling this before generate_policy when working inside the user's project, with a rationale that policies from actual code are better. While it doesn't enumerate all alternatives or exclusion cases, it provides clear context for primary use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get copy-paste instructions for wiring a generated policy into the user's site: hosted link, embed snippet, and framework-specific placement. Call this after generate_policy to finish the job — a generated policy helps nobody until it's linked from the site.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The policy ID (UUID) to integrate. | |
| framework | No | The site's framework, for tailored snippets (default: html). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and open world; the description adds value by specifying the output contains a hosted link, embed snippet, and framework-specific placement. 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?
Two sentences, zero wasted words, front-loaded with the core purpose. Efficient and to the point.
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 lookup tool with 2 parameters and no output schema, the description provides sufficient context: purpose, workflow dependency, and output nature. A minor gap is lack of details about the returned embed snippet format, but it's adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions. The description mentions 'framework-specific placement', reinforcing the 'framework' parameter, but doesn't add substantial meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves 'copy-paste instructions for wiring a generated policy into the user's site', specifying both the verb (Get) and resource (integration guide). It distinguishes from siblings like 'generate_policy' by indicating this is a follow-up step.
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 instructs to call this after 'generate_policy' to complete the workflow, and highlights that a generated policy 'helps nobody until it's linked from the site'. This provides clear contextual guidance for when 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.
Retrieve a single policy by ID, including its status, hosted URL, and full Markdown content.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The policy ID (UUID) returned by generate_policy or list_policies. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, so the description's claim of retrieving data is consistent. It adds value by specifying the returned fields (status, URL, Markdown), providing context beyond the annotations. 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, well-structured sentence that front-loads the main action and includes all necessary details without extraneous words. Every part 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 simple tool with only one required parameter and no output schema, the description is comprehensive enough. It identifies the output components (status, hosted URL, Markdown) and the input source, making the tool 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 coverage is 100%, but the description explains the 'id' parameter's origin (UUID from generate_policy or list_policies), adding semantic meaning beyond the schema's type and length 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 clearly states the tool retrieves a single policy by ID, including specific fields (status, hosted URL, Markdown content). It uses a specific verb 'retrieve' and specifies the resource, distinguishing it from sibling tools like list_policies (multiple) and generate_policy (creation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a policy ID, but it does not explicitly state when to use this tool versus alternatives like list_policies or when not to use it. No exclusions or alternative tool mentions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the account's subscription tier and remaining policy-generation quota. Call this before generate_policy on accounts that may be on the free tier, so you can plan instead of hitting quota errors.
| 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 openWorldHint=true. The description adds that it returns subscription tier and quota, which aligns with annotations and provides specific behavioral context without 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?
Two sentences; the first front-loads the purpose, the second provides actionable usage guidance. 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?
For a simple read-only tool with no parameters and no output schema, the description fully covers purpose, usage context, and behavioral expectations. It is complete for agent decision-making.
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 no parameters, so schema description coverage is 100%. The description does not need to add parameter semantics; baseline is 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 'Check the account's subscription tier and remaining policy-generation quota' with a specific verb and resource, and it distinguishes itself from sibling tools like generate_policy or list_policies by focusing on usage/quota.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises calling this tool before generate_policy on free-tier accounts to avoid quota errors, providing clear when-to-use context and an alternative (planning instead of error handling).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the policies previously created on this PolicyForge account, newest first.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Filter by policy type. | |
| limit | No | Max results (1-100, default 20). | |
| offset | No | Pagination offset. | |
| sortBy | No | Sort field (default updatedAt). | |
| status | No | Filter by status. | |
| sortOrder | No | Sort direction (default desc). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so the description correctly implies no side effects. It adds that results are returned 'newest first,' which matches the default sortOrder in the schema. There is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the purpose and default ordering without any extraneous information. It is front-loaded 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?
Considering the tool is a simple list operation with no output schema and 6 well-described parameters, the description is sufficient. It could optionally mention pagination or filtering, but the parameters cover those. The description is complete enough for an agent to understand the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters are well-documented in the schema. The description only adds the ordering default ('newest first'), which is helpful but not critical. With high schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'policies', specifies the scope 'on this PolicyForge account', and notes the default sort order 'newest first'. It distinguishes from sibling tools like generate_policy or get_policy by focusing on listing existing policies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for viewing existing policies, but does not explicitly state when to use this tool versus alternatives (e.g., get_policy for a single policy). However, the context signals and sibling tools make it reasonably clear, and the description provides the default behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the supported policy types, business types, and jurisdictions accepted by generate_policy. Call this first if unsure which enum values are valid.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and description adds context about listing enums. No contradictions, though lacks detail on output format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and then usage. 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 0 params and no output schema, description is complete: tells purpose and when to use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, schema coverage 100%. Baseline 4 applies; description adds no param info but doesn't need to.
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 lists supported policy types, business types, and jurisdictions, and names the related tool generate_policy. This distinguishes it 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 instructs 'Call this first if unsure which enum values are valid.' Provides 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.
Version history for a policy: snapshots taken before every API update, regeneration, or restore, plus any auto-generated compliance update drafts. Use get-version content via restore_policy_version, or fetch a single version's content with this policy's versions endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The policy ID (UUID). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds significant behavioral context beyond annotations (readOnlyHint, openWorldHint): it explains that snapshots are taken before updates, regenerations, restores, and include compliance drafts. 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 main purpose. Second sentence could be more concise, but overall it's efficient and clear with minimal 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 one parameter and no output schema, the description covers the tool's purpose and key behavioral aspects. Lacks details on pagination or ordering, but sufficient for a simple list 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?
Only one parameter (id) with full schema coverage. Description adds context by referring to 'this policy's versions endpoint', implying id is the policy identifier, which is a slight improvement over 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?
Clearly states it lists version history for a policy, specifies what snapshots are included (before API updates, regeneration, restore, compliance drafts), and distinguishes from siblings by mentioning restore_policy_version and fetching single version content.
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 context on when to use (for version history) and mentions alternative actions (restore or fetch single version). Lacks explicit when-not-to-use instructions, but the guidance is clear for typical usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-run the AI generation engine over a policy's stored business context merged with the changed fields you provide — same policy ID and hosted URL, so published links keep working. The previous content is saved as a version first (see list_policy_versions / restore_policy_version). Consumes one generation from quota, like generate_policy. Use this when the business context changed substantially (new integrations, new jurisdiction, renamed company); for small wording fixes prefer update_policy, which is free and instant.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The policy ID (UUID) to regenerate. | |
| cookies | No | Does it use cookies? Defaults to true for most websites. | |
| payments | No | Does it process payments? | |
| analytics | No | Does it use analytics? | |
| dpo_email | No | Data Protection Officer email, if any. Also sets hasDPO. | |
| marketing | No | Does it send marketing communications? | |
| sells_data | No | Does it sell or share personal data? | |
| website_url | No | Company website URL. | |
| company_name | No | Changed company name. | |
| jurisdiction | No | Changed legal framework(s), e.g. "gdpr,ccpa". | |
| business_type | No | Changed business category. | |
| children_data | No | Does it knowingly collect data from children? | |
| contact_email | No | Changed contact email. | |
| governing_law | No | Governing law jurisdiction, e.g. "State of California, USA". | |
| user_accounts | No | Does the product have user accounts? | |
| data_retention | No | How long data is kept, e.g. "24 months". | |
| stack_manifest | No | Structured summary of the stack you detected while scanning the codebase (see get_disclosure_checklist), e.g. {"analytics":["posthog"],"payments":["stripe"],"auth":["supabase"],"ai_features":["openai"],"cookies":["session"],"jurisdiction_signals":["EU locales"]}. Stored server-side so check_policy_freshness can detect drift when the stack changes later. Provide it whenever you scanned the project. | |
| data_collection | No | Categories of personal data collected, e.g. ["email","name","usage"]. | |
| target_audience | No | Audience segments, e.g. ["businesses","consumers"]. | |
| physical_address | No | Company physical address. | |
| security_measures | No | Security controls, e.g. ["encryption at rest","MFA"]. | |
| table_of_contents | No | Add a linked table of contents to the generated document. Requires a Pro plan. | |
| service_description | No | Short description of what the product or service does. | |
| third_party_integrations | No | Third-party processors, e.g. ["Stripe","Google Analytics"]. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses key side effects: previous content is automatically saved as a version, it consumes one generation from quota, and the hosted URL stays stable. This provides valuable context for a mutating, non-read-only tool and explains the destructiveHint without contradicting it.
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 dense sentences: what it does, key side effects, and when to use it. No filler; each sentence serves a distinct purpose and is front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 24 parameters and no output schema, the description covers the essential operational context: what gets regenerated, what happens to old content, quota cost, URL stability, and alternatives. It also references the versioning workflow, making it complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and every parameter has a description, so the description doesn't need to restate them. It adds useful context by framing the fields as 'changed fields' merged over stored business context, with examples like 'new integrations, new jurisdiction, renamed company.' This enhances understanding without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Re-run the AI generation engine over a policy's stored business context merged with the changed fields you provide.' It clearly distinguishes itself from siblings by explicitly noting it preserves the same policy ID and hosted URL, and it contrasts with generate_policy (new policy) and update_policy (small fixes).
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 given: 'Use this when the business context changed substantially... for small wording fixes prefer update_policy, which is free and instant.' It also references related tools (list_policy_versions / restore_policy_version) and clarifies quota implications, making it unambiguous when to choose this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore a policy to a previous version from list_policy_versions. The current content is snapshotted as a new version first, so a restore is itself reversible. The hosted URL is unchanged.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The policy ID (UUID). | |
| version | Yes | The version_number to restore (from list_policy_versions). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructive, idempotent), the description adds critical behavioral details: current content is snapshotted as a new version before restore, making it reversible, and the hosted URL remains unchanged. 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 concise sentences with no wasted words. The first sentence states the purpose, the second adds behavioral context. 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?
Given two required parameters, no output schema, and annotations covering safety, the description provides sufficient context: purpose, behavior (snapshot, reversibility, URL unchanged), and reference to sibling tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear descriptions for both parameters. The description adds no additional meaning beyond what the 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?
The description uses a specific verb ('Restore') and resource ('policy') and explicitly references sibling tool 'list_policy_versions' for obtaining the version, distinguishing it from similar tools like update_policy.
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 does not provide explicit guidance on when to use this tool versus alternatives, nor does it state prerequisites or when not to use it. It only implies the version number comes from list_policy_versions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing policy in place — the policy ID, hosted URL, and embed keep working, so links already published on the user's site stay valid. Use this instead of generate_policy when the business context changed (new SDK, new data flow, renamed company): fetch the current content with get_policy, revise the Markdown yourself, and submit it here. Note: there is no version history — the previous content is overwritten.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The policy ID (UUID) to update. | |
| title | No | New policy title. | |
| status | No | Change publication status. Only 'published' policies are served at the hosted URL. | |
| content | No | Full replacement Markdown content. Submit the COMPLETE document, not a diff. | |
| effective_date | No | New effective date, ISO format e.g. "2026-07-13". | |
| hosting_enabled | No | Enable/disable the public hosted page. | |
| consent_tracking | No | Enable/disable the "I agree" consent banner on the hosted page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses critical behavioral traits beyond annotations: 'the previous content is overwritten' and 'no version history', which aligns with destructiveHint and idempotentHint. It also explains that links stay valid, adding valuable context. 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 (three sentences) and front-loaded with the core purpose. Each sentence provides essential information without redundancy, and the structure flows logically from purpose to usage to caution.
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 (7 parameters, no output schema), the description covers all critical aspects: in-place update, link persistence, use-case differentiation, workflow, and behavioral side effects (overwrite). It sufficiently prepares the agent for 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?
While schema description coverage is 100%, the description adds meaningful guidance: the content parameter should be the 'COMPLETE document, not a diff'. This clarifies the intended usage beyond the schema's basic description. The in-place update nature is also reinforced. A slight improvement could mention the effective_date 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 explicitly states 'Update an existing policy in place' and highlights that links remain valid, distinguishing it from siblings like generate_policy. The verb 'update' and resource 'policy' are specific, and the scope (in-place, no ID change) is clear.
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 instead of generate_policy when the business context changed'. It also outlines a concrete workflow (fetch with get_policy, revise Markdown, submit here) and warns about the lack of version history, helping the agent decide appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.6.1generate_policy1 field changedInput schema / properties / table_of_contentsAdded value: +{
+ "description": "Add a linked table of contents to the generated document. Requires a Pro plan.",
+ "type": "boolean"
+}regenerate_policy1 field changedInput schema / properties / table_of_contentsAdded value: +{
+ "description": "Add a linked table of contents to the generated document. Requires a Pro plan.",
+ "type": "boolean"
+}v0.5.0audit_compliancecheck_policy_freshnessdelete_policygenerate_baagenerate_policyget_disclosure_checklistget_integration_guideget_policyget_usagelist_policieslist_policy_typeslist_policy_versionsregenerate_policyrestore_policy_versionupdate_policyScored across 15 tools
Most tools target clear resource-action pairs, and the detailed guidance for update_policy vs regenerate_policy and audit_compliance vs check_policy_freshness keeps confusion low. A couple of update/compliance tools share conceptual territory, so an agent may need to read descriptions carefully before choosing.
All tool names follow a consistent snake_case verb_noun pattern: get_*, list_*, generate_*, update_*, restore_*, and delete_*. Even multiword names like check_policy_freshness and get_disclosure_checklist fit the same convention cleanly.
At 15 tools, the surface is at the high end of the ideal range but each tool addresses a distinct lifecycle stage or compliance workflow. It is slightly heavy, especially with both update_policy and regenerate_policy plus overlapping compliance checks, but not bloated.
The core policy lifecycle is well covered: create, read, update, delete, versioning, integration guidance, quota checks, and compliance auditing. The main gap is that generate_baa introduces a distinct document type without clear BAA-specific update, version, or delete coverage.
One-step legal compliance for vibe-coded apps: privacy, terms, cookie banner and EU AI Act check.
Compliance lint for AI, scraping, and privacy law. Cited findings in 200 or more jurisdictions.
Pre-action allow/deny for AI agents. 24 statutes, 13 jurisdictions: EU AI Act, GDPR, DPDP.
Open-source licence risk checks for AI coding agents and dependency trees.
