pdfnative-mcp

Draft a governance-compliant GitHub issue (HITL)

draft_governance_issue

Idempotent

Drafts a local GitHub issue and compliance report for human review, checking reproduction and zero-dependency rules without submitting or writing to GitHub.

Instructions

Produce a LOCAL GitHub issue draft + compliance report for pdfnative / pdfnative-mcp and NEVER submit it — the agent drafts, a human reviews and files it under their own identity (Human-In-The-Loop contract, .github/AGENT_RULES.md). No GitHub write path exists. The draft is checked against the zero-dependency + reproduction policy; a violation (new runtime dependency, missing reproduction, duplicateSearchPerformed:false) throws GOVERNANCE_VIOLATION. Returns markdown inline (outputMode:'file' also writes a .md). Present the draft AND the report to the user, then STOP.

Input Schema

Name	Required	Description	Default
`title`	Yes	Concise issue title (imperative, no trailing period).
`summary`	Yes	One or two paragraphs describing the problem or proposal.
`issueType`	Yes	Issue category: 'bug' \| 'feature' \| 'security' \| 'docs' \| 'performance'.
`outputMode`	No	'inline' (default) returns the draft markdown in the response. 'file' additionally writes it to the sandbox (requires PDFNATIVE_MCP_OUTPUT_DIR); outputPath must be a relative .md path.	inline
`outputPath`	No	Relative .md path inside the sandbox (only when outputMode='file').
`targetRepo`	No	Destination repository label for the draft (documentation only — the server never contacts it). Typically 'pdfnative-mcp' or 'pdfnative'.	pdfnative-mcp
`reproduction`	Yes	The minimal, locally-executed reproduction that justifies this issue.
`actualBehavior`	No	What actually happened (defaults to the reproduction result when omitted).
`affectedPackages`	No	Packages impacted by this issue (e.g. ["pdfnative-mcp"], ["pdfnative"]).
`expectedBehavior`	Yes	What you expected to happen instead.
`duplicateSearchPerformed`	Yes	MUST be true: confirms you searched open AND closed issues/PRs for duplicates before drafting.

Output Schema

Name	Required	Description
`url`	No	Public URL of the draft (file mode, only when PDFNATIVE_MCP_OUTPUT_BASE_URL is set).
`title`	Yes
`filePath`	No	Sandboxed absolute path (when outputMode='file').
`warnings`	Yes
`issueType`	Yes
`sizeBytes`	Yes
`compliance`	Yes
`outputMode`	Yes
`targetRepo`	Yes
`draftMarkdown`	Yes	The full draft, ready for a human to review and submit.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.8.0Nov 3, 2026

addedOutput schema / properties / url

Added value: +{
+  "description": "Public URL of the draft (file mode, only when PDFNATIVE_MCP_OUTPUT_BASE_URL is set).",
+  "type": "string"
+}

Addedv1.4.0Jul 5, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnly=false, idempotent=true, destructive=false; the description adds substantive behavior the agent could not infer: validation against zero-dependency and reproduction policy, a thrown GOVERNANCE_VIOLATION on specific violations, and the file-mode requirement for PDFNATIVE_MCP_OUTPUT_DIR. It also resolves the apparent contradiction between 'draft' and a non-destructive write by clarifying nothing is ever submitted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core contract in the first clause and ends with a crisp stop instruction. It is dense—multiple policy references (AGENT_RULES.md, zero-dependency, reproduction policy, duplicateSearchPerformed) are packed into two long sentences—but nearly every clause carries decision-relevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 11 parameters (6 required, one nested object), an output schema, and full annotation coverage, the description supplies the missing behavioral layer: no external write happens, validation can throw, and output goes inline or to a sandbox file. An agent has everything needed to call it correctly and to know what to do with the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 earns above that by tying specific parameters to behavior—outputMode:'file' writing a .md, and duplicateSearchPerformed:false being a violation trigger. Only targetRepo's documentation-only nature and these hints are restated from the schema rather than adding wholly new meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and artifact: 'Produce a LOCAL GitHub issue draft + compliance report' for a named repo, and explicitly negates the confusing action ('NEVER submit it'). The purpose is unmistakable and clearly disjoint from the PDF-manipulation siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operating context (Human-In-The-Loop contract, .github/AGENT_RULES.md, 'No GitHub write path exists') and a terminal instruction ('Present the draft AND the report to the user, then STOP'). It stops short of naming when to prefer this over alternatives or prerequisites like searching duplicates first, but with no real sibling overlap the guidance is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.