pdfnative-mcp

Draft a governance-compliant GitHub issue (HITL)

draft_governance_issue

Idempotent

Draft a local GitHub issue with compliance checks for zero-dependency and reproducible bugs, leaving submission to a human reviewer.

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

TableJSON 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

TableJSON Schema

Name	Required	Description
`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.

Addedv1.4.0Jul 5, 2026

TDQS

A4.7/5.0

Behavior5/5

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

The description goes beyond the annotation set and provides crucial behavioral context: the draft is never submitted, a human files it, no GitHub write path exists, policy violations raise GOVERNANCE_VIOLATION, and the agent must present output and then STOP. This is exactly the kind of non-obvious behavior an autonomous agent needs.

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

Conciseness5/5

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

The description is compact yet information-dense. Critically, it front-loads the key constraints (LOCAL, NEVER submit, HITL) and includes the procedural end state ('present the draft AND the report to the user, then STOP') with no wasted words.

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?

Given the 11 parameters, nested reproduction object, output schema, and annotations, this description still closes all important gaps: the governance policy, violation behavior, output modes, human review step, and stop condition. An agent has enough to invoke the tool and interpret its guidance correctly.

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?

Even though the input schema describes every parameter thoroughly, the description adds meaningful behavioral requirements: duplicateSearchPerformed:false triggers a GOVERNANCE_VIOLATION, and outputMode 'file' writes a .md file. These enrich the interpretation of the parameters beyond their simple schema definitions.

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?

The description clearly states the action ('Produce a LOCAL GitHub issue draft + compliance report'), the resource ('for pdfnative / pdfnative-mcp'), and the critical boundary ('NEVER submit it'). It is fully differentiated from the PDF-manipulation siblings by the explicit issue-drafting scope.

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?

It clearly establishes when to use the tool: when an issue draft is needed under the Human-In-The-Loop contract and must not be submitted. It also tells the agent it does not provide a GitHub write path, implying it should not be used for actual issue submission, though no explicit alternative tool is named.

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