design_tool_contract

Instructions

Implementation Reference

• src/mcp_template/modules/design.py:86-116 (handler)

  The async function `design_tool_contract` that implements the tool logic: generates a design-time contract preview for a future MCP tool based on tool_name, purpose, side_effects, and auth_required.

  async def design_tool_contract(
      tool_name: str,
      purpose: str,
      side_effects: Literal["none", "read", "write", "external-io"] = "read",
      auth_required: bool = False,
  ) -> ToolContractPreview:
      """Generate a design-time contract preview for a future MCP tool."""
      with container.metrics.observe_tool("design_tool_contract"):
          guidance = [
              "Define crisp input schema boundaries and validation failures.",
              "Return structured output instead of free-form text when clients may chain this tool.",
              "Document idempotency and side effects in the tool description.",
          ]
          if side_effects in {"write", "external-io"}:
              guidance.append("Add retries, timeout budgets, and audit logging before production rollout.")
          if auth_required:
              guidance.append("Gate the tool behind scopes that map to a specific trust boundary.")
          return ToolContractPreview(
              tool_name=tool_name,
              purpose=purpose,
              side_effects=side_effects,
              auth_required=auth_required,
              recommended_annotations={
                  "readOnlyHint": side_effects == "none",
                  "idempotentHint": side_effects in {"none", "read"},
                  "destructiveHint": side_effects == "write",
                  "openWorldHint": side_effects == "external-io",
              },
              schema_sections=["inputs", "validation", "structured_output", "error_contract"],
              operational_guidance=guidance,
          )

• src/mcp_template/modules/design.py:82-84 (registration)

  The `@server.tool` decorator registering the tool with name 'design_tool_contract' and annotations (readOnlyHint, idempotentHint).

  @server.tool(
      name="design_tool_contract",
      annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True, openWorldHint=False),

• src/mcp_template/types/models.py:119-126 (schema)

  The `ToolContractPreview` Pydantic model defining the structured return type of the tool (tool_name, purpose, side_effects, auth_required, recommended_annotations, schema_sections, operational_guidance).

  class ToolContractPreview(TemplateModel):
      tool_name: str
      purpose: str
      side_effects: Literal["none", "read", "write", "external-io"]
      auth_required: bool
      recommended_annotations: dict[str, bool]
      schema_sections: list[str]
      operational_guidance: list[str]

• src/mcp_template/modules/design.py:190-199 (helper)

  The `register` function returns a ModuleDescriptor that lists 'design_tool_contract' among the tools provided by the 'design' module.

  return ModuleDescriptor(
      name="design",
      title="Design",
      summary="Future-facing design tools for elicitation, sampling, and capability planning.",
      tags=["planning", "elicitation", "sampling"],
      maturity="beta",
      tools=["design_collect_feature_brief", "design_tool_contract", "design_refine_with_sampling"],
      resources=["template://production-readiness", "template://module/{name}"],
      prompts=["design_rollout_plan"],
  )