Guidance for AI‑Friendly Capability Annotations for Supported $filter Option

[chrisspre]

Problem
Modern AI agents can reliably generate syntactically valid OData query options—including $filter—when given a CSDL model.
However, they consistently struggle to generate service‑supported filter expressions, because:

• The CSDL describes legal expressions, not supported ones
• OData Capability annotations do not currently expose enough detail for an agent (or an MCP service author) to know which filter patterns the service actually implements
• Many services support only a subset of the theoretically legal $filter expressions, often depending on backend indexing, data shape, or runtime constraints
  As a result, AI agents frequently produce $filter expressions that are valid but rejected by the service at runtime.

Gap
There is no existing vocabulary that allows a service to declare:

• Which $filter patterns are supported
• Which properties can be filtered with which operators (we have one that gives it which property is allowed but not in which "position")
• Which functions are allowed
• Which combinations are valid
• Any dynamic or implementation‑specific constraints
  This leaves both AI agents and human authors guessing.

[chrisspre]

Proposal
Introduce Guidance and/or a new annotation vocabulary that allows a service to enumerate examples of supported $filter expressions.
The annotation would contain:

• A list of example $filter expressions that the service guarantees to support
• A short description for each example explaining its semantics or constraints
• Optional grouping or categorization (e.g., “string filters”, “numeric comparisons”, “date functions”, “ID‑based filters”)
  The intent is not to exhaustively enumerate all possibilities, but to provide representative, service‑supported patterns that an LLM can generalize from.

Rationale
LLMs are extremely good at:

• Learning patterns from examples
• Extrapolating consistent variants
• Respecting constraints when they are expressed concretely
  LLMs are not good at:
• Inferring dynamic service capabilities from CSDL alone
• Guessing which operators or functions are supported
• Understanding backend‑specific limitations without examples
  Providing explicit examples gives the agent enough grounding to reliably generate $filter expressions that the service will accept.

Example Sketch

<Annotations Target="MyService.Model.EntitySet/Orders">
  <Annotation Term="Org.OData.Guidance.SupportedFilterExamples">
    <Collection>
      <Record>
        <PropertyValue Property="Filter" String="Status eq 'Open'" />
        <PropertyValue Property="Description" String="Simple equality on string enum-like property." />
      </Record>
      <Record>
        <PropertyValue Property="Filter" String="OrderDate ge 2024-01-01" />
        <PropertyValue Property="Description" String="Date comparison supported only on OrderDate." />
      </Record>
      <Record>
        <PropertyValue Property="Filter" String="contains(CustomerName, 'Smith')" />
        <PropertyValue Property="Description" String="String functions supported only on CustomerName." />
      </Record>
    </Collection>
  </Annotation>
</Annotations>

[chrisspre]

Feedback from Alive Vinograova https://www.linkedin.com/in/oisee/

Couple of thoughts: looks good and useful!

Strong +1 for this proposal — it addresses a real pain point when building MCP services that wrap OData endpoints.
The example-based approach is pragmatic and aligns well with how LLMs learn. However, I'd suggest considering and explore complementary (?) generalized on-demand capability discovery mechanism that extends beyond $filter to all query options.

odata-filter-capabilities-analysis.md
odata-capability-discovery-generalized.md