Task Progress:
- [ ] Step 1: Parse input and extract API contract
- [ ] Step 2: Determine tool name and resource file
- [ ] Step 3: Implement tool function
- [ ] Step 4: Register tool in tools.go
- [ ] Step 5: Write unit tests
- [ ] Step 6: Update README.md Available Tools table
- [ ] Step 7: Run linter — fix errors
- [ ] Step 8: Run tests — fix errors
- [ ] Step 9: Create branch, commit, and open PR (if gh available)

func ToolName(
	obs *observability.Observability,
	client *rzpsdk.Client,
) mcpgo.Tool {
	parameters := []mcpgo.ToolParameter{
		// Required params first, then optional
	}

	handler := func(
		ctx context.Context,
		r mcpgo.CallToolRequest,
	) (*mcpgo.ToolResult, error) {
		client, err := getClientFromContextOrDefault(ctx, client)
		if err != nil {
			return mcpgo.NewToolResultError(err.Error()), nil
		}

		payload := make(map[string]interface{})
		validator := NewValidator(&r).
			ValidateAndAddRequiredString(payload, "id")
			// chain more validators...

		if result, err := validator.HandleErrorsIfAny(); result != nil {
			return result, err
		}

		response, err := client.Resource.Method(/* args */)
		if err != nil {
			return mcpgo.NewToolResultError(
				fmt.Sprintf("operation failed: %s", err.Error())), nil
		}

		return mcpgo.NewToolResultJSON(response)
	}

	return mcpgo.NewTool("tool_name", "description", parameters, handler)
}

[Action verb] + [what it does] + [key context].
[When to use / prerequisites]. [Constraints, units, or return format].

// Vague — LLM doesn't know when to pick this
"Fetch an order's details using its ID"

// No constraints — LLM won't know about paise
"Create a new standard payment link in Razorpay with a specified amount"

// Missing trigger context
"Fetch all QR codes with optional filtering and pagination"

// Clear what, when, and constraints
"Retrieve details of a specific payment by its ID. " +
	"Use when you need payment status, method, or amount. " +
	"Amount returned is in paise (100 paise = ₹1)."

// Prerequisites + constraints
"Capture a previously authorized payment to settle funds. " +
	"Only works on payments with status 'authorized'. " +
	"Amount in paise; partial capture supported."

// Trigger context + return format
"Get all saved payment methods (cards, UPI) " +
	"for a contact number. " +
	"Use when the user wants to pay with a saved method. " +
	"Returns token IDs that can be used with initiate_payment."

// When to use + what makes it different
"Create a UPI-specific payment link (generates a UPI QR). " +
	"Use instead of create_payment_link when the customer " +
	"will pay via UPI. Only supports INR currency."

import (
	"context"
	"fmt"

	rzpsdk "github.com/razorpay/razorpay-go"

	"github.com/razorpay/razorpay-mcp-server/pkg/mcpgo"
	"github.com/razorpay/razorpay-mcp-server/pkg/observability"
)

newResource := toolsets.NewToolset("resource_name", "Description").
	AddReadTools(FetchResource(obs, client)).
	AddWriteTools(CreateResource(obs, client))
toolsetGroup.AddToolset(newResource)

import (
	"fmt"
	"net/http"
	"net/http/httptest"
	"testing"

	"github.com/razorpay/razorpay-go/constants"

	"github.com/razorpay/razorpay-mcp-server/pkg/razorpay/mock"
)

// Base path (POST/list endpoints)
basePath := fmt.Sprintf("/%s%s",
	constants.VERSION_V1, constants.RESOURCE_URL)

// Path with ID (GET/PATCH single resource)
pathFmt := fmt.Sprintf("/%s%s/%%s",
	constants.VERSION_V1, constants.RESOURCE_URL)

func Test_ToolName(t *testing.T) {
	apiPath := fmt.Sprintf("/%s%s",
		constants.VERSION_V1, constants.RESOURCE_URL)

	successResponse := map[string]interface{}{
		// from docs
	}

	errorResponse := map[string]interface{}{
		"error": map[string]interface{}{
			"code":        "BAD_REQUEST_ERROR",
			"description": "error message",
		},
	}

	tests := []RazorpayToolTestCase{
		{
			Name:    "successful operation",
			Request: map[string]interface{}{/* all params */},
			MockHttpClient: func() (*http.Client, *httptest.Server) {
				return mock.NewHTTPClient(mock.Endpoint{
					Path: apiPath, Method: "POST",
					Response: successResponse,
				})
			},
			ExpectError:    false,
			ExpectedResult: successResponse,
		},
		// ... negative cases
	}

	for _, tc := range tests {
		t.Run(tc.Name, func(t *testing.T) {
			runToolTest(t, tc, ToolName, "Resource")
		})
	}
}

| `tool_name` | Brief description | [Resource](docs_url) | ✅ or ❌ |

golangci-lint run ./pkg/razorpay/...

go test ./pkg/razorpay/... -v -count=1

gh api user --jq '.login'

# 1. Ensure we're on a clean main
git checkout main
git pull origin main

# 2. Create feature branch
git checkout -b USERNAME/feat-TOOL_NAME

# 3. Stage all changes
git add pkg/razorpay/{resource}.go \
       pkg/razorpay/{resource}_test.go \
       pkg/razorpay/tools.go \
       README.md

# 4. Commit with conventional format
git commit -m "feat: add TOOL_NAME tool"

# 5. Push and create PR
git push -u origin HEAD
gh pr create \
  --title "feat: add TOOL_NAME tool" \
  --body "$(cat <<'EOF'
## Summary
- Add `tool_name` tool for [brief description]
- Implements [HTTP method] [endpoint path]
- Includes unit tests with full coverage

## Test plan
- [ ] `go test ./pkg/razorpay/... -v -run Test_ToolName`
- [ ] `golangci-lint run ./pkg/razorpay/...`
- [ ] Manual verification with MCP client (optional)

## References
- API docs: [link]
EOF
)"

VERSION_V1       = "v1"
ORDER_URL        = "/orders"
PAYMENT_URL      = "/payments"
PaymentLink_URL  = "/payment_links"
REFUND_URL       = "/refunds"
CUSTOMER_URL     = "/customers"
QRCODE_URL       = "/payments/qr_codes"
SETTLEMENT_URL   = "/settlements"
PAYOUT_URL       = "/payouts"