Align 'return type schema' section with the FunctionCalling_ReturnMetadata sample

[Federico Laurianti (Laurianti)]

Addresses microsoft/semantic-kernel#11202

The Providing functions return type schema to LLM section of the C# pivot used an ad-hoc LightsPlugin example and did not explain how the three techniques differ. This change aligns it with the official FunctionCalling_ReturnMetadata sample:

• replaces the snippets with the WeatherData plugins and the filter from the sample, including the kernel setup and the expected output
• adds a comparison table: when the information reaches the model (function advertisement vs. invocation), whether type information is included, and whether it is maintained by hand or extracted automatically
• explains why the sample uses generic property names (Data1..Data4) and restates that descriptive names should be the first choice
• links the sample from the docs

Docs-only change, no code. The Python pivot is untouched.

[learn-build-service-prod]

Learn Build status updates of commit 997a241:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
semantic-kernel/concepts/plugins/index.md	⚠️Warning		Details
semantic-kernel/concepts/plugins/adding-native-plugins.md	✅Succeeded

semantic-kernel/concepts/plugins/index.md

• Line 447, Column 44: [Warning: bookmark-not-found - See documentation] Cannot find bookmark '#provide-function-return-type-information-in-function-description' in 'concepts/plugins/adding-native-plugins.md'.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

[Copilot]

🟡 Changes recommended

The documentation examples are not runnable as shown, and navigation and metadata updates remain unresolved.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Updates the C# return-type schema documentation to align with the official FunctionCalling_ReturnMetadata sample.

Changes:

• Replaces ad-hoc examples with WeatherData plugins and filter usage.
• Adds technique comparisons, expected outputs, and maintenance guidance.
• Links the official sample and explains property naming choices.

File summaries

File	Summary
semantic-kernel/concepts/plugins/adding-native-plugins.md	Updated C# return-type metadata guidance. Two moderate issues remain with undeclared setup variables, plus nits for navigation, wording, and metadata updates.

Review details

Suppressed comments (5)

semantic-kernel/concepts/plugins/adding-native-plugins.md:460

• This new kernel setup is not runnable as shown: modelId and apiKey are never declared anywhere in this page. Replace these identifiers with the literal placeholders used by the other C# setup examples, or define them before this block.

    .AddOpenAIChatCompletion(modelId, apiKey)

semantic-kernel/concepts/plugins/adding-native-plugins.md:583

• This repeated kernel setup has the same copy/paste error: modelId and apiKey are not declared in the page, so the example does not compile as shown. Use literal model/key placeholders or define these values before the snippet.

    .AddOpenAIChatCompletion(modelId, apiKey)

semantic-kernel/concepts/plugins/adding-native-plugins.md:426

• The Automatic maintenance entry is too broad: this technique generates the schema automatically, but the [Description] attributes on Data1–Data4 are still authored and maintained manually when the property meanings change. Qualify the cell to distinguish automatic schema generation from manual descriptions.

| Return type schema as part of the return value | During function invocation, only for the functions actually called | Yes | Automatic |

semantic-kernel/concepts/plugins/adding-native-plugins.md:418

• This page has C#, Python, and Java pivots but no language-parity table. Add a small HTML table after the frontmatter that records this return-metadata section as C#-specific (or add equivalent sections for the other languages), so future edits do not silently leave the pivots out of sync.

The examples below come from the [FunctionCalling_ReturnMetadata](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/FunctionCalling/FunctionCalling_ReturnMetadata.cs) sample. The properties of the `WeatherData` class are intentionally given generic names (`Data1`, `Data2`, `Data3`, `Data4`) for demonstration purposes only: this prevents the model from making assumptions about their content based solely on their names, and forces it to rely on the other return type metadata (descriptions or schemas) to reason about them. In your own plugins, descriptive property names should always be the first choice.

semantic-kernel/concepts/plugins/adding-native-plugins.md:418

• This concept-page update leaves the document metadata incomplete: ms.date is still 07/12/2023, and the required language-parity HTML comment is absent after the frontmatter. Please update the date to 09/13/2026 and add a parity table marking this return-metadata section as C#-specific (with the Python/Java exclusions explained).

The examples below come from the [FunctionCalling_ReturnMetadata](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/FunctionCalling/FunctionCalling_ReturnMetadata.cs) sample. The properties of the `WeatherData` class are intentionally given generic names (`Data1`, `Data2`, `Data3`, `Data4`) for demonstration purposes only: this prevents the model from making assumptions about their content based solely on their names, and forces it to rely on the other return type metadata (descriptions or schemas) to reason about them. In your own plugins, descriptive property names should always be the first choice.

• Files reviewed: 1/1 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Federico Laurianti (Laurianti)]

Addressed the review in the second commit:

• restored the original #### Provide function return type information in function description heading, so the anchor used by concepts/plugins/index.md keeps working (the Learn build warning is gone)
• kernel setup now uses the same placeholders as the rest of the repo ("gpt-4", Environment.GetEnvironmentVariable("OpenAI__ApiKey"))
• the table now distinguishes the automatically extracted schema from the hand-written property descriptions
• ms.date bumped

Not applied: the language-parity HTML table. None of the seven pages under concepts/plugins/ has one, so I did not introduce a convention that does not exist in this folder; happy to add it if the docs team wants it.

[learn-build-service-prod]

Learn Build status updates of commit fd577f0:

✅ Validation status: passed

File	Status	Preview URL	Details
semantic-kernel/concepts/plugins/adding-native-plugins.md	✅Succeeded

For more details, please refer to the build report.

[Federico Laurianti (Laurianti)]

@microsoft-github-policy-service agree