Use config parameter descriptions in GraphQL stored procedure args

[anushakolan]

Why make this change?

• Closes [Bug]: Param descriptions not surfaced in GraphQL #3500.
  • GraphQL stored-procedure argument descriptions were not honoring runtime config parameter descriptions and could show generic or database-only text. This made schema docs less useful for API consumers.
  • Additional discussion threads: [Fix]: Ensure MCP handles parameters properly #3506

What is this change?

• Updated stored-procedure GraphQL argument description resolution to use this precedence:
  • source.parameters[].description from runtime config (when present)
  • database parameter description (when present)
  • fallback text (parameters for <stored-procedure> stored-procedure)
• Added regression tests to verify config-description precedence and fallback behavior.
  • GraphQL spec reference (Descriptions): https://spec.graphql.org/October2021/#sec-Descriptions

How was this tested?

• Integration Tests
• Unit Tests

Focused unit test run:

dotnet test .\src\Service.Tests\Azure.DataApiBuilder.Service.Tests.csproj --filter "StoredProcedure_ParameterDescription_UsesConfigDescription|StoredProcedure_ParameterDescription_FallsBackToDatabaseDescription|StoredProcedure_RequiredWithDefault_KeepsDefaultValue|StoredProcedure_RequiredFlag_ProducesNonNullType"

Sample Request(s)

• Example GraphQL introspection request:

query {
  __type(name: "Mutation") {
    fields {
      name
      args {
        name
        description
      }
    }
  }
}

• Example CLI usage:

dotnet "src/out/engine/net10.0/Azure.DataApiBuilder.Service.dll" --ConfigFileName "dab-config.verify-3500.json"

[Copilot]

Pull request overview

Updates GraphQL stored-procedure argument description generation so schema docs prefer runtime config parameter descriptions, improving introspection/docs quality for API consumers (per #3500).

Changes:

• Updated GraphQLStoredProcedureBuilder to resolve argument descriptions with precedence: config description → DB/definition description → default fallback text.
• Added unit tests validating config-description precedence and DB-description fallback for stored-procedure args.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
src/Service.GraphQLBuilder/GraphQLStoredProcedureBuilder.cs	Applies new description precedence logic when building stored-procedure GraphQL argument definitions.
src/Service.Tests/GraphQLBuilder/Sql/StoredProcedureBuilderTests.cs	Adds regression tests for config-vs-DB description precedence on stored-procedure arguments.

[Aniruddh25]

can we really get description of a parameter from database metadata?

the definition here maybe showing the property Description, but are you sure it can get populated by querying the database? Did you test that?

[Aniruddh25]

Approved, but left some questions.

[aaronburtle]

This test doesn't exercise the production path that appears responsible for the underlying issue. During normal initialization, both SQL metadata-provider implementations copy ParameterMetadata.Description onto ParameterDefinition.Description before GraphQL schema generation. Therefore, the old builder should also return the config description after normal metadata initialization.

Here the test bypasses that merge and manually creates a state where paramMetadata.Description == configDescription while definition.Description == dbDescription. That proves the new builder-level precedence, but it does not reproduce the reported production bug.

Could we add a regression test that starts from runtime config, initializes the metadata provider, builds the GraphQL schema, and asserts the argument description through introspection? Ideally, that test should fail on the PR's base commit. If it already passes on the base, we should identify and cover the specific path.

[aaronburtle]

This direct config lookup creates first-wins behavior for descriptions because FirstOrDefault() selects the first matching parameter. Metadata hydration has different behavior: it iterates the complete parameter list and repeatedly assigns to the same ParameterDefinition, so the last duplicate wins.

The parameter-array schema currently does not enforce uniqueness by name. For a config containing two title entries with different descriptions, GraphQL would now expose the first description while OpenAPI/MCP can expose the last merged description.

Could we either reject duplicate parameter names during semantic config validation or use the normalized ParameterDefinition consistently here? Rejecting duplicates would be preferable because it also removes ambiguity for required and default.

[aaronburtle]

nit:
Could we add cases where the config description is "" or " " and the definition description is populated, plus a case where both values are empty/whitespace? That would verify both whitespace fallback branches and protect the behavior that this PR is introducing.