Improvements to the LLM-facing tool design #180

Here is a summary of multiple questions and possibilities discussed with @esgn on how to improve the tool designs for easier handling by the LLM.

GpfDescribeType

Standard compliance

Should the tool output faithfully reproduce the OGC API Feature Schema?

• Pros: it will be the current state after Adapt to upstream gpf-schema-store v0.2.2 #179 (minus the required $id field). It's also simpler to maintain and corresponds to a standard.
• Cons: some improvements could be made in our case:
  • const and title are systematically redundant in our database, we should only keep one of the two.
  • the geometry (geometries?) should have special handling rather than being displayed like other properties because, otherwise, the LLM believes it can select it. This is problematic because we don't want huge geometries to enter the LLM context, so it is tracked by a dedicated error path, but the LLM still attempts it sometimes (gpf_wfs_get_features - why rejecting geometry in select? #82). One mitigation consists in removing the geometry from the output list (Hide the geometric property in GpfDescribeType #176) so that the LLM does not even know how to access the geometry (except through the dedicated layer tools).

Additional fields

We could add additional fields to the output to guide the LLM on the possible usage of this typename. Could be:

• spatial_filters_available: true or false depending on whether the collection has a geometric property or not.
• spatial_extras_list: that could be the exact list of queryable spatial_extras. We could exclude bbox on Point geometries for example.
• geometry_type: point, linestring, point-or-multipoint, etc. Especially useful if the geometric property was removed from the displayed list of properties.

GpfGetFeatureById

Name

Should we rename it into GpfGetFeatureByRef?

• Pros: more consistent with feature_ref naming.
• Cons: the name is still quite clear in the current state.

Input

Should we merge the feature_ref two fields into a single string?

• Pros: the LLM handles a single string rather than two fields so it's easier.
• Cons: the current state allows the LLM to know what the typename is, which is useful in order to run GpfDescribeType.

GpfGetFeatures / GpfGetFeatureById

Should the tools return a GeoJSON?

• Pros: it's the current state and, again, it's standard. Also the LLM may want to write a program that works on all GeoJSON and use it on the output of GpfGetFeatures as well as GpfGetFeaturesLayer (although I don't see why it could not simply use the output of the latter).
• Cons: it doesn't really make sense considering that we never return the geometry. It also forces us to specify a geometry: null field which is incorrect, because it usually means that the feature does not have a geometry.

Instead, @esgn proposes we could return something like:

{
  "typename": "BDTOPO_V3:batiment",
  "numberReturned": 1,
  "numberMatched": 42,
  "truncated": false,
  "items": [
    {
      "id": "batiment.123",
      "properties": { },
      "spatial": { },
      "feature_ref": { }
    }
  ]
}

(I approve but I suggest removing typename and id, which are redundant with feature_ref.)

An additional option consists in returning the properties in a table, rather than as key/value pairs, to reduce the redundancy in their names across the different features. That would reduce the token size of the output, but it feels less LLM-friendly.