microsoft-learn-research

microsoft-learn-research

Impact tier: P1 -- Operational Readiness

Purpose

General-purpose research skill for querying the Microsoft Learn MCP server to resolve Azure architecture questions, validate configurations against official documentation, and fill knowledge gaps. This is the meta-skill referenced by all other skills in this pack when they need MCP queries. It documents best practices for query construction, result filtering, citation format, and escalation when MCP results are insufficient.

When to Use

• Before patching any Azure resource configuration: retrieve the canonical Microsoft recommendation first.
• When an unfamiliar Azure service parameter is encountered in IaC.
• When a gap audit references a Microsoft Learn URL that needs full content.
• When other skills' MCP queries return insufficient results and need refinement.

Required Evidence (inspect these repo paths first)

Microsoft Learn MCP Usage

This skill IS the MCP query skill. The three available tools are:

microsoft_docs_search

Breadth search across Microsoft Learn. Returns up to 10 document chunks.

Best practices:

• Use 4-8 specific terms. Vague queries return generic results.
• Include the Azure service name AND the specific feature: "Azure Container Apps VNet integration" not just "container apps networking".
• Include the action or concept: "private access disable public" not just "security".
• Append SDK language when relevant: "Python SDK", "Bicep", "REST API".

microsoft_docs_search("Azure PostgreSQL Flexible Server private access VNet integration Bicep")
microsoft_docs_search("Azure AI Foundry Agent Service Python SDK v2 create agent")
microsoft_docs_search("Azure Container Apps health probes liveness readiness startup Bicep")

microsoft_code_sample_search

Targeted code sample search. Supports language filter.

Best practices:

• Use for specific implementation patterns, not conceptual questions.
• Always specify language when searching for IaC or SDK code.
• Combine service name with the specific pattern: "bicep postgresql flexible server zone redundant ha".

microsoft_code_sample_search("bicep container app managed identity key vault", language="bicep")
microsoft_code_sample_search("azure foundry agent python create thread run", language="python")
microsoft_code_sample_search("bicep postgresql flexible server vnet delegation private dns", language="bicep")

microsoft_docs_fetch

Retrieves the full markdown of a known Microsoft Learn URL. Use when a microsoft_docs_search result references a page that needs complete content.

Best practices:

• Always use learn.microsoft.com URLs, not external links.
• Fetch when you need a complete parameter reference table, not just a snippet.
• Cache the result in docs/evidence/<stamp>/<skill>/mcp-fetch-<slug>.md.

microsoft_docs_fetch("https://learn.microsoft.com/en-us/azure/postgresql/flexible-server/concepts-networking-private")
microsoft_docs_fetch("https://learn.microsoft.com/en-us/azure/container-apps/scale-app")
microsoft_docs_fetch("https://learn.microsoft.com/en-us/azure/ai-services/agents/overview")

Workflow

1. Inspect repo -- Confirm .codex/config.toml has the MCP server registered. Confirm the skill README authority order. Identify which Azure service and feature the research question targets.
2. Query MCP -- Start with microsoft_docs_search (2-3 queries, refining terms if results are too broad). If results reference specific URLs, use microsoft_docs_fetch. If implementation code is needed, use microsoft_code_sample_search.
3. Compare -- Map MCP results to the current repo state. Note any parameter values, API shapes, or architectural recommendations that differ from IaC or SSOT.
4. Patch -- Apply the finding: update IaC, SSOT YAML, or runbook. Always cite the MCP source in a comment: # Source: microsoft_docs_search("<query>").
5. Verify -- Confirm the patched file is syntactically valid (Bicep lint, Python ruff, YAML parse). Commit evidence with MCP excerpts.

Outputs

Completion Criteria

• .codex/config.toml confirms MCP server at https://learn.microsoft.com/api/mcp.
• Each MCP query result is cited in code comments or evidence files using the format: # Source: microsoft_docs_search("<query>").
• No configuration value was invented: every parameter came from repo evidence, MCP results, or existing SSOT.
• Evidence directory contains the raw MCP query and result for each research question answered.
• If MCP returned no useful results for a query, the gap is flagged explicitly in the evidence file as BLOCKED: MCP returned insufficient results for "<query>".