feat(mcp): LLM-friendly filter, search, sort and include descriptions

binaryk · binaryk · commit 0e6cde29e5d3 · 2026-07-11T16:26:20.000+03:00
- MatchFilter: honor setDescription() overrides; rewrite default
  templates as concise single sentences (grammar + typo fixes)
- SearchablesCollection: fix fieldNames() always returning empty
  (entries are SearchableFilter objects, not strings)
- McpIndexTool: omit search/sort schema params when unavailable,
  list real searchable fields, drop the redundant matcher prefix
- McpToolHelpers: append the related repository's purpose one-liner
  to each relationship in the include documentation
diff --git a/src/Filters/MatchFilter.php b/src/Filters/MatchFilter.php
@@ -132,24 +132,22 @@ public function usingClosure(Closure $closure): self
 
     public function description(): string
     {
-        $description = "This is a exact match for $this->column (e.g., $this->column=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -$this->column=some_value). The filter type is string.";
-
-        if ($this->getType() === RestifySearchable::MATCH_BETWEEN) {
-            $description = "This is a range match for $this->column (e.g., $this->column=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -$this->column=value1,value2). Accepted values can be any.";
-        }
-
-        if ($this->getType() === RestifySearchable::MATCH_DATETIME) {
-            $description = "This is a date match for $this->column (e.g., $this->column=YYYY-MM-DD or $this->column=value1,value2 for range). It accepts negation by prefixing the column with a hyphen (e.g., -$this->column=YYYY-MM-DD or -$this->column=value1,value2 for range). Accepted values are date.";
-        }
-
-        if ($this->getType() === RestifySearchable::MATCH_BOOL) {
-            $description = "This is a boolean match for $this->column (e.g., $this->column=true or $this->column=false). It accepts negation by prefixing the column with a hyphen (e.g., -$this->column=true or -$this->column=false). Accepted values are boolean.";
+        if ($this->description !== '') {
+            return $this->description;
         }
 
-        if ($this->getType() === RestifySearchable::MATCH_ARRAY) {
-            $description = "This is an array match for $this->column (e.g., $this->column=value1,value2). It accepts negation by prefixing the column with a hyphen (e.g., -$this->column=value1,value2). The values acccepted can be any.";
-        }
+        return $this->defaultDescription();
+    }
 
-        return $description;
+    protected function defaultDescription(): string
+    {
+        return match ($this->getType()) {
+            RestifySearchable::MATCH_BETWEEN => "Range match on $this->column ($this->column=min,max). Prefix with '-' to negate (-$this->column=min,max).",
+            RestifySearchable::MATCH_DATETIME => "Date match on $this->column ($this->column=YYYY-MM-DD, or $this->column=start,end for a range). Prefix with '-' to negate (-$this->column=YYYY-MM-DD).",
+            RestifySearchable::MATCH_BOOL, 'boolean' => "Boolean match on $this->column ($this->column=true or $this->column=false). Prefix with '-' to negate (-$this->column=true).",
+            RestifySearchable::MATCH_ARRAY => "Array match on $this->column ($this->column=value1,value2 matches any listed value). Prefix with '-' to negate (-$this->column=value1,value2).",
+            RestifySearchable::MATCH_INTEGER, 'number', 'int' => "Exact match on $this->column ($this->column=value). Prefix with '-' to negate (-$this->column=value).",
+            default => "Exact match on $this->column ($this->column=value). Prefix with '-' to negate (-$this->column=value).",
+        };
     }
 }
diff --git a/src/Filters/SearchablesCollection.php b/src/Filters/SearchablesCollection.php
@@ -55,10 +55,17 @@ public function __construct($items = [])
      */
     public function fieldNames(): array
     {
-        return $this->filter(fn ($item) => is_string($item) && ! empty($item))
-            ->unique()
-            ->values()
-            ->toArray();
+        $columns = [];
+
+        foreach ($this->all() as $item) {
+            $column = $item instanceof Filter ? $item->column() : (is_string($item) ? $item : null);
+
+            if (is_string($column) && $column !== '' && $column !== 'unknown') {
+                $columns[] = $column;
+            }
+        }
+
+        return array_values(array_unique($columns));
     }
 
     /**
diff --git a/src/MCP/Concerns/McpIndexTool.php b/src/MCP/Concerns/McpIndexTool.php
@@ -36,10 +36,12 @@ public static function indexToolSchema(JsonSchema $schema): array
                 ->description(static::formatRelationshipDocumentation(app(McpIndexRequest::class))),
         ];
 
-        $searchableFields = (new SearchablesCollection(static::searchables()))->formatForDocumentation();
+        $searchableFields = (new SearchablesCollection(static::searchables()))->fieldNames();
 
-        $properties['search'] = $schema->string()
-            ->description("Search term to filter $key by name or description. Available searchable fields: {$searchableFields} (e.g., search=term)");
+        if (! empty($searchableFields)) {
+            $properties['search'] = $schema->string()
+                ->description('Full-text search across: '.implode(', ', $searchableFields).' (search=term).');
+        }
 
         $sortOptions = collect(static::sorts())
             ->map(function ($value, $key) {
@@ -52,26 +54,29 @@ public static function indexToolSchema(JsonSchema $schema): array
 
                 return $key;
             })
+            ->filter(fn ($option) => is_string($option) && $option !== '')
             ->values()
             ->toArray();
 
-        $properties['sort'] = $schema->string()
-            ->description("Sorting criteria for the $key. Available options: ".implode(', ',
-                $sortOptions).' (e.g., sort=field or sort=-field for descending)');
+        if (! empty($sortOptions)) {
+            $properties['sort'] = $schema->string()
+                ->description("Sort $key by one of: ".implode(', ', $sortOptions).". Prefix with '-' for descending (sort=field or sort=-field).");
+        }
 
         MatchesCollection::make(static::matches())
             ->normalize()
             ->authorized(app(McpRequest::class))
-            ->each(function (MatchFilter $matchFilter) use ($schema, $key, &$properties) {
+            ->each(function (MatchFilter $matchFilter) use ($schema, &$properties) {
                 $filterKey = $matchFilter->column();
+                $description = $matchFilter->description();
 
                 $properties[$filterKey] = match ($matchFilter->getType()) {
                     RestifySearchable::MATCH_INTEGER, 'integer' => $schema->integer()
-                        ->description("Filter $key resource. Description: ".$matchFilter->description()),
+                        ->description($description),
                     RestifySearchable::MATCH_BOOL, 'boolean' => $schema->boolean()
-                        ->description("Filter $key resource. Description: ".$matchFilter->description()),
+                        ->description($description),
                     default => $schema->string()
-                        ->description("Filter $key resource. Description: ".$matchFilter->description())
+                        ->description($description)
                 };
             });
 
diff --git a/src/MCP/Concerns/McpToolHelpers.php b/src/MCP/Concerns/McpToolHelpers.php
@@ -52,7 +52,8 @@ protected static function formatRelationshipDocumentation(McpRequest $request):
             if ($repositoryClass) {
                 $fields = static::getRelationshipFields($repositoryClass, $request);
                 $fieldsList = implode(', ', $fields);
-                $documentation .= "- {$relationName} (fields: {$fieldsList})\n";
+                $purpose = static::getRelationshipPurpose($repositoryClass);
+                $documentation .= "- {$relationName} (fields: {$fieldsList}){$purpose}\n";
                 $relationshipClasses[$relationName] = $repositoryClass;
             } else {
                 $documentation .= "- {$relationName}\n";
@@ -102,6 +103,23 @@ protected static function formatRelationshipDocumentation(McpRequest $request):
         return $documentation;
     }
 
+    protected static function getRelationshipPurpose(string $repositoryClass): string
+    {
+        if (! is_subclass_of($repositoryClass, Repository::class)) {
+            return '';
+        }
+
+        $custom = $repositoryClass::$description ?? '';
+
+        if (! is_string($custom) || $custom === '') {
+            return '';
+        }
+
+        $firstSentence = trim(strtok($custom, '.'));
+
+        return $firstSentence === '' ? '' : " - {$firstSentence}.";
+    }
+
     protected static function extractRepositoryClass($relationConfig): ?string
     {
         // Handle string repository class
diff --git a/tests/Controllers/RepositoryFilterControllerTest.php b/tests/Controllers/RepositoryFilterControllerTest.php
@@ -79,7 +79,7 @@ public function test_filters_will_render_placeholder(): void
     {
         PostRepository::$match = [
             'title' => MatchFilter::make()
-                ->setDescription('Sort by title')
+                ->setDescription('Filter posts by their title.')
                 ->setPlaceholder('-title')
                 ->setType('string'),
         ];
@@ -90,10 +90,27 @@ public function test_filters_will_render_placeholder(): void
             ->assertJson(function (AssertableJson $json) {
                 $json
                     ->where('data.0.placeholder', '-title')
-                    ->where('data.0.description', 'This is a exact match for title (e.g., title=some_value). It accepts negation by prefixing the column with a hyphen (e.g., -title=some_value). The filter type is string.')
+                    ->where('data.0.description', 'Filter posts by their title.')
                     ->where('data.0.type', 'string')
                     ->where('data.0.column', 'title')
                     ->etc();
             });
     }
+
+    public function test_match_filter_renders_default_description_when_not_customized(): void
+    {
+        PostRepository::$match = [
+            'title' => MatchFilter::make()->setType('string'),
+        ];
+
+        $this->getJson(PostRepository::route('filters', query: [
+            'only' => 'matches',
+        ]))
+            ->assertJson(function (AssertableJson $json) {
+                $json
+                    ->where('data.0.description', "Exact match on title (title=value). Prefix with '-' to negate (-title=value).")
+                    ->where('data.0.column', 'title')
+                    ->etc();
+            });
+    }
 }
diff --git a/tests/MCP/McpIndexToolSchemaTest.php b/tests/MCP/McpIndexToolSchemaTest.php
@@ -0,0 +1,149 @@
+<?php
+
+namespace Binaryk\LaravelRestify\Tests\MCP;
+
+use Binaryk\LaravelRestify\Contracts\RestifySearchable;
+use Binaryk\LaravelRestify\Filters\MatchFilter;
+use Binaryk\LaravelRestify\MCP\Concerns\HasMcpTools;
+use Binaryk\LaravelRestify\Repositories\Repository;
+use Binaryk\LaravelRestify\Restify;
+use Binaryk\LaravelRestify\Tests\Fixtures\Post\Post;
+use Binaryk\LaravelRestify\Tests\IntegrationTestCase;
+use Illuminate\JsonSchema\JsonSchemaTypeFactory;
+
+class McpIndexToolSchemaTest extends IntegrationTestCase
+{
+    protected function tearDown(): void
+    {
+        Restify::$repositories = [];
+
+        parent::tearDown();
+    }
+
+    protected function repositoryWith(array $search = [], array $sort = [], array $match = []): Repository
+    {
+        return new class($search, $sort, $match) extends Repository
+        {
+            use HasMcpTools;
+
+            public static $model = Post::class;
+
+            public static array $search = [];
+
+            public static array $sort = [];
+
+            public static array $match = [];
+
+            public function __construct(array $search = [], array $sort = [], array $match = [])
+            {
+                self::$search = $search;
+                self::$sort = $sort;
+                self::$match = $match;
+            }
+        };
+    }
+
+    protected function schema(Repository $repository): array
+    {
+        return $repository::indexToolSchema(new JsonSchemaTypeFactory);
+    }
+
+    public function test_search_property_lists_searchable_fields(): void
+    {
+        $schema = $this->schema($this->repositoryWith(search: ['id', 'title']));
+
+        $this->assertArrayHasKey('search', $schema);
+
+        $description = $schema['search']->toArray()['description'];
+
+        $this->assertStringContainsString('Full-text search across: id, title', $description);
+        $this->assertStringNotContainsString('No searchable fields available', $description);
+        $this->assertStringNotContainsString('by name or description', $description);
+    }
+
+    public function test_search_property_is_omitted_when_no_searchables(): void
+    {
+        $schema = $this->schema($this->repositoryWith(search: []));
+
+        $this->assertArrayNotHasKey('search', $schema);
+    }
+
+    public function test_sort_property_lists_sort_options(): void
+    {
+        $schema = $this->schema($this->repositoryWith(sort: ['title', 'is_active']));
+
+        $this->assertArrayHasKey('sort', $schema);
+
+        $description = $schema['sort']->toArray()['description'];
+
+        $this->assertStringContainsString('title', $description);
+        $this->assertStringContainsString('is_active', $description);
+        $this->assertStringContainsString("Prefix with '-' for descending", $description);
+    }
+
+    public function test_matcher_property_uses_description_without_clunky_prefix(): void
+    {
+        $schema = $this->schema($this->repositoryWith(match: [
+            'title' => RestifySearchable::MATCH_TEXT,
+        ]));
+
+        $this->assertArrayHasKey('title', $schema);
+
+        $description = $schema['title']->toArray()['description'];
+
+        $this->assertStringNotContainsString('Description:', $description);
+        $this->assertStringNotContainsString('resource.', $description);
+        $this->assertSame(
+            "Exact match on title (title=value). Prefix with '-' to negate (-title=value).",
+            $description
+        );
+    }
+
+    public function test_matcher_property_respects_custom_description(): void
+    {
+        $schema = $this->schema($this->repositoryWith(match: [
+            'title' => MatchFilter::make()
+                ->setType(RestifySearchable::MATCH_TEXT)
+                ->setDescription('Filter posts by their title.'),
+        ]));
+
+        $this->assertSame(
+            'Filter posts by their title.',
+            $schema['title']->toArray()['description']
+        );
+    }
+
+    public function test_default_templates_per_match_type(): void
+    {
+        $cases = [
+            RestifySearchable::MATCH_TEXT => "Exact match on col (col=value). Prefix with '-' to negate (-col=value).",
+            RestifySearchable::MATCH_INTEGER => "Exact match on col (col=value). Prefix with '-' to negate (-col=value).",
+            RestifySearchable::MATCH_BOOL => "Boolean match on col (col=true or col=false). Prefix with '-' to negate (-col=true).",
+            RestifySearchable::MATCH_BETWEEN => "Range match on col (col=min,max). Prefix with '-' to negate (-col=min,max).",
+            RestifySearchable::MATCH_DATETIME => "Date match on col (col=YYYY-MM-DD, or col=start,end for a range). Prefix with '-' to negate (-col=YYYY-MM-DD).",
+            RestifySearchable::MATCH_ARRAY => "Array match on col (col=value1,value2 matches any listed value). Prefix with '-' to negate (-col=value1,value2).",
+        ];
+
+        foreach ($cases as $type => $expected) {
+            $filter = MatchFilter::make()->setColumn('col')->setType($type);
+
+            $this->assertSame($expected, $filter->description(), "Failed default template for [{$type}].");
+        }
+    }
+
+    public function test_default_templates_have_no_grammar_or_typo_bugs(): void
+    {
+        foreach ([
+            RestifySearchable::MATCH_TEXT,
+            RestifySearchable::MATCH_BETWEEN,
+            RestifySearchable::MATCH_DATETIME,
+            RestifySearchable::MATCH_BOOL,
+            RestifySearchable::MATCH_ARRAY,
+        ] as $type) {
+            $description = MatchFilter::make()->setColumn('col')->setType($type)->description();
+
+            $this->assertStringNotContainsString('a exact match', $description);
+            $this->assertStringNotContainsString('acccepted', $description);
+        }
+    }
+}
diff --git a/tests/MCP/WrapperToolsIntegrationTest.php b/tests/MCP/WrapperToolsIntegrationTest.php
@@ -514,7 +514,7 @@ public function mcpAllowsIndex(): bool
         $this->assertArrayHasKey('properties', $schema);
         $this->assertArrayHasKey('page', $schema['properties']);
         $this->assertArrayHasKey('perPage', $schema['properties']);
-        $this->assertArrayHasKey('search', $schema['properties']);
+        $this->assertArrayNotHasKey('search', $schema['properties']);
         $this->assertArrayHasKey('include', $schema['properties']);
 
         // Assert examples are provided
