Skip to main content
Glama
smeet666

mcp-stashbox

by smeet666
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Search scenes

search_scenes
Read-only

Find scenes across multiple stash-box catalogues using text queries or filters for performer, tag, studio, date, and sort. Results are returned per catalogue, indicating matches, misses, or empty sets.

Instructions

Search scenes across every configured stash-box catalogue. Two exclusive paths: 'query' runs each catalogue's own text index, which reads the words as a union, and the typed arguments narrow as an intersection. Writing both is refused. The answer says per catalogue which of three it met: a failure, a catalogue nobody asked, and an emptiness it established. Counts are never added across them.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
codeNo
dateNo
pageNoWhich page of its own order every catalogue asked is read at, counted from 1. A search written with words alone reads the first rows each text index answers with, since those routes take no page.
sortNo
aliasNoNo catalogue's faceted route applies it, though every faceted input declares it: a request carrying it answers as wide as one carrying none, so it is never sent and the answer names it as a narrowing nobody received.
limitNoHow many rows one page of one catalogue carries. An answer holding several carries up to this many from each: their pages are their own and nothing here interleaves them into one.
matchNoHow performer_ids and tag_ids are read, which are the only arguments it governs. 'all', the default, asks for scenes carrying every identifier of a list; 'any' for scenes carrying at least one, which answers counts an order of magnitude wider. A scene names one studio, so studio_ids asks for any of its identifiers under both readings. The lists narrow against each other as an intersection either way.
queryNoWords for the catalogue's own text index, which reads them as a union. It is exclusive with the typed arguments, which narrow as an intersection.
titleNo
sourcesNo
tag_idsNo
directionNo
studio_idsNo
date_compareNoThese catalogues compare a date against one bound and answer no range, so the comparison is written rather than assumed.
performer_idsNo
parent_studio_idNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
notesYes
cachedNoReplayed from this client's store.
windowNoThe page and the row limit this answer was read at, absent where no catalogue answered.
resultsYes
orderingYesHow the rows were laid out, which a reader needs before reading the first.
per_sourceYes
result_countYesHow many rows this page carries.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed26 schema fields changedv1.0.0
    • addedInput schema / properties / alias / description
      Added value: +"No catalogue's faceted route applies it, though every faceted input declares it: a request carrying it answers as wide as one carrying none, so it is never sent and the answer names it as a narrowing nobody received."
    • changedInput schema / properties / limit / description
      Previous value: -"How many rows one page of one catalogue carries. An answer holding several catalogues carries up to this many from each of them, since their pages are their own and nothing here interleaves them into one."New value: +"How many rows one page of one catalogue carries. An answer holding several carries up to this many from each: their pages are their own and nothing here interleaves them into one."
    • addedInput schema / properties / match / description
      Added value: +"How performer_ids and tag_ids are read, which are the only arguments it governs. 'all', the default, asks for scenes carrying every identifier of a list; 'any' for scenes carrying at least one, which answers counts an order of magnitude wider. A scene names one studio, so studio_ids asks for any of its identifiers under both readings. The lists narrow against each other as an intersection either way."
    • changedInput schema / properties / page / description
      Previous value: -"The page of each catalogue's own order. A route that reads words alone takes no page, and the answer reports it as one that catalogue did not receive."New value: +"Which page of its own order every catalogue asked is read at, counted from 1. A search written with words alone reads the first rows each text index answers with, since those routes take no page."
    • changedOutput schema / properties / per_source / items / properties / index_total / description
      Previous value: -"What its own index holds for this question, the rows on this page included."New value: +"What its own index holds for the question it received, the rows on this page included. A narrowing it could not receive, or received in part, leaves that question wider than the one written."
    • changedOutput schema / properties / per_source / items / properties / narrowings_not_received / description
      Previous value: -"Narrowings this catalogue cannot receive. This is the one field that says a catalogue cannot do something."New value: +"Narrowings that shaped no part of the request this catalogue received, whether its route declares no field for one or nothing written was left for one to decide."
    • addedOutput schema / properties / per_source / items / properties / narrowings_received_in_part / description
      Added value: +"Narrowings it received short of what was written, the rest of the list naming records another catalogue minted. It answered a wider question than the one asked."
    • addedOutput schema / properties / results / items / properties / also_held_at
      Added value: +{
+  "description": "The same record on another catalogue, read from a link this one publishes to it. A shared name is no join.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "type": "string"
+      },
+      "source": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "source",
+      "id"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
    • addedOutput schema / properties / results / items / properties / code
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "The studio's own reference for the release."
+}
    • addedOutput schema / properties / results / items / properties / duration_seconds
      Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "The runtime that catalogue holds, which is what separates two cuts of one title."
+}
    • addedOutput schema / properties / results / items / properties / linked_unfollowed
      Added value: +{
+  "description": "A link to another catalogue naming the record by something this client cannot address. The link is written, and following it is what failed.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "source": {
+        "type": "string"
+      },
+      "url": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "source",
+      "url"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
    • addedOutput schema / properties / results / items / properties / pending_edits
      Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Edits open against it, null where its catalogue publishes no such count."
+}
    • addedOutput schema / properties / results / items / properties / pending_edits_unreadable
      Added value: +{
+  "description": "The count of open edits came back in a shape this client could not read.",
+  "type": "boolean"
+}
    • addedOutput schema / properties / results / items / properties / performers
      Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "creditedAs": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "The name this release printed, where it differs."
+      },
+      "disambiguation": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "id": {
+        "type": "string"
+      },
+      "name": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      },
+      "status": {
+        "enum": [
+          "established",
+          "merged",
+          "deleted"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "name",
+      "creditedAs",
+      "disambiguation",
+      "status"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
    • addedOutput schema / properties / results / items / properties / production_date_unreadable
      Added value: +{
+  "description": "The same, for the production date, which get_scene answers with.",
+  "type": "boolean"
+}
    • addedOutput schema / properties / results / items / properties / release_date
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "precision": {
+          "description": "How much of the date the catalogue holds: a month or a year can be all of it.",
+          "enum": [
+            "day",
+            "month",
+            "year"
+          ],
+          "type": "string"
+        },
+        "value": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "value",
+        "precision"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}
    • addedOutput schema / properties / results / items / properties / release_date_unreadable
      Added value: +{
+  "description": "A release date was published in a shape this client could not read, so the null above is a reading that failed rather than a date nobody entered.",
+  "type": "boolean"
+}
    • addedOutput schema / properties / results / items / properties / retrieved_at
      Added value: +{
+  "description": "The moment this client read it there.",
+  "type": "string"
+}
    • addedOutput schema / properties / results / items / properties / rows_skipped
      Added value: +{
+  "description": "Entries of this record's own lists that could not be read and are left out.",
+  "type": "number"
+}
    • addedOutput schema / properties / results / items / properties / rows_skipped_in
      Added value: +{
+  "description": "Which of its lists lost them.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • addedOutput schema / properties / results / items / properties / status / description
      Added value: +"What the identifier addresses on that catalogue now. A folded record answers with a marker, which describes the record and never what it once named."
    • addedOutput schema / properties / results / items / properties / studio
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "name": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "parent": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "parentWithdrawn": {
+          "type": "boolean"
+        },
+        "status": {
+          "enum": [
+            "established",
+            "merged",
+            "deleted"
+          ],
+          "type": "string"
+        }
+      },
+      "required": [
+        "id",
+        "name",
+        "parent",
+        "status"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}
    • addedOutput schema / properties / results / items / properties / tags
      Added value: +{
+  "description": "Each tag with the identifier the next call takes. What its catalogue filed it under is a fact about the tag, which get_tag answers.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "type": "string"
+      },
+      "name": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "null"
+          }
+        ]
+      }
+    },
+    "required": [
+      "id",
+      "name"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
    • addedOutput schema / properties / results / items / properties / title
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}
    • changedOutput schema / properties / results / items / required
      Previous value: -[
-  "id",
-  "source",
-  "source_url",
-  "status"
-]New value: +[
+  "id",
+  "source",
+  "source_url",
+  "retrieved_at",
+  "status",
+  "also_held_at",
+  "linked_unfollowed",
+  "title",
+  "code",
+  "duration_seconds",
+  "release_date",
+  "studio",
+  "performers",
+  "tags"
+]
    • changedOutput schema / properties / window / description
      Previous value: -"The page a catalogue paged through, absent where none was given one."New value: +"The page and the row limit this answer was read at, absent where no catalogue answered."
  2. Changed64 schema fields changedv0.9.0
    • addedInput schema / properties / alias
      Added value: +{
+  "minLength": 1,
+  "type": "string"
+}
    • removedInput schema / properties / code / description
      Removed value: -"The studio's own reference for the scene."
    • addedInput schema / properties / code / minLength
      Added value: +1
    • addedInput schema / properties / date
      Added value: +{
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}
    • addedInput schema / properties / date_compare
      Added value: +{
+  "description": "These catalogues compare a date against one bound and answer no range, so the comparison is written rather than assumed.",
+  "enum": [
+    "on",
+    "before",
+    "after"
+  ],
+  "type": "string"
+}
    • removedInput schema / properties / date_from
      Removed value: -{
-  "description": "Released strictly after this date, as YYYY-MM-DD. A catalogue takes one date comparison at a time, so giving both bounds sends this one and reports the other as not received.",
-  "type": "string"
-}
    • removedInput schema / properties / date_to
      Removed value: -{
-  "description": "Released strictly before this date, as YYYY-MM-DD.",
-  "type": "string"
-}
    • addedInput schema / properties / limit / description
      Added value: +"How many rows one page of one catalogue carries. An answer holding several catalogues carries up to this many from each of them, since their pages are their own and nothing here interleaves them into one."
    • removedInput schema / properties / match / description
      Removed value: -"How a list of identifiers reads. 'all' returns scenes carrying every one of them and is the default; 'any' returns scenes carrying at least one."
    • addedInput schema / properties / page / description
      Added value: +"The page of each catalogue's own order. A route that reads words alone takes no page, and the answer reports it as one that catalogue did not receive."
    • changedInput schema / properties / page / maximum
      Previous value: -10000New value: +1000
    • addedInput schema / properties / parent_studio_id
      Added value: +{
+  "pattern": "^(?:(?:stashdb|tpdb|fansdb|pmv|javstash):)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+  "type": "string"
+}
    • removedInput schema / properties / performer_ids / description
      Removed value: -"Namespaced performer identifiers."
    • addedInput schema / properties / performer_ids / items / pattern
      Added value: +"^(?:(?:stashdb|tpdb|fansdb|pmv|javstash):)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    • addedInput schema / properties / performer_ids / maxItems
      Added value: +25
    • addedInput schema / properties / performer_ids / minItems
      Added value: +1
    • changedInput schema / properties / query / description
      Previous value: -"Free text matched against a scene's own fields."New value: +"Words for the catalogue's own text index, which reads them as a union. It is exclusive with the typed arguments, which narrow as an intersection."
    • addedInput schema / properties / query / minLength
      Added value: +1
    • changedInput schema / properties / sort / enum
      Previous value: -[
-  "title",
-  "date",
-  "duration",
-  "created",
-  "updated"
-]New value: +[
+  "title",
+  "date",
+  "duration",
+  "trending",
+  "popularity",
+  "created_at",
+  "updated_at"
+]
    • addedInput schema / properties / sources / items / enum
      Added value: +[
+  "stashdb",
+  "tpdb",
+  "fansdb",
+  "pmv",
+  "javstash"
+]
    • addedInput schema / properties / sources / maxItems
      Added value: +5
    • addedInput schema / properties / sources / minItems
      Added value: +1
    • addedInput schema / properties / studio_ids / items / pattern
      Added value: +"^(?:(?:stashdb|tpdb|fansdb|pmv|javstash):)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    • addedInput schema / properties / studio_ids / maxItems
      Added value: +25
    • addedInput schema / properties / studio_ids / minItems
      Added value: +1
    • addedInput schema / properties / tag_ids / items / pattern
      Added value: +"^(?:(?:stashdb|tpdb|fansdb|pmv|javstash):)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    • addedInput schema / properties / tag_ids / maxItems
      Added value: +25
    • addedInput schema / properties / tag_ids / minItems
      Added value: +1
    • addedInput schema / properties / title / minLength
      Added value: +1
    • changedOutput schema / properties / cached / description
      Previous value: -"Present when the answer came from the in-memory store."New value: +"Replayed from this client's store."
    • changedOutput schema / properties / ordering / description
      Previous value: -"How the order was built. The catalogues publish no score in common, so rows interleave and nothing is ranked across them."New value: +"How the rows were laid out, which a reader needs before reading the first."
    • addedOutput schema / properties / per_source / items / properties / algorithms_not_searched
      Added value: +{
+  "description": "Fingerprint algorithms its lookup does not search, so they were never put to it.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • changedOutput schema / properties / per_source / items / properties / count / description
      Previous value: -"Rows this catalogue contributed to this page."New value: +"Rows it contributed. Never added to another catalogue's: they index corpora that overlap by an amount none of them publishes."
    • addedOutput schema / properties / per_source / items / properties / error / enum
      Added value: +[
+  "not_found",
+  "invalid_input",
+  "rate_limited",
+  "parse_failure",
+  "network_error",
+  "timeout"
+]
    • removedOutput schema / properties / per_source / items / properties / fields_searched
      Removed value: -{
-  "description": "The fields the text index read. Absent where no text index was consulted.",
-  "items": {
-    "type": "string"
-  },
-  "type": "array"
-}
    • changedOutput schema / properties / per_source / items / properties / index_total / description
      Previous value: -"What this catalogue's index holds for the question, beyond the page returned."New value: +"What its own index holds for this question, the rows on this page included."
    • addedOutput schema / properties / per_source / items / properties / index_total_over_any_word
      Added value: +{
+  "description": "The total counts rows carrying any word of the query, its text index reading them apart.",
+  "type": "boolean"
+}
    • changedOutput schema / properties / per_source / items / properties / moment / description
      Previous value: -"Which step failed, for a catalogue that failed."New value: +"Which moment failed."
    • addedOutput schema / properties / per_source / items / properties / name / description
      Added value: +"The name that catalogue calls itself."
    • addedOutput schema / properties / per_source / items / properties / narrowings_naming_no_record
      Added value: +{
+  "description": "Narrowings written only with identifiers another catalogue minted.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • changedOutput schema / properties / per_source / items / properties / narrowings_not_received / description
      Previous value: -"Narrowings this catalogue could not receive. A row of its satisfying one of them does so by chance."New value: +"Narrowings this catalogue cannot receive. This is the one field that says a catalogue cannot do something."
    • addedOutput schema / properties / per_source / items / properties / narrowings_received_in_part
      Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • addedOutput schema / properties / per_source / items / properties / reason / description
      Added value: +"Why it was not asked, or what went wrong."
    • addedOutput schema / properties / per_source / items / properties / records
      Added value: +{
+  "description": "Distinct records behind its rows.",
+  "type": "number"
+}
    • addedOutput schema / properties / per_source / items / properties / skipped / description
      Added value: +"Rows it answered with that this client could not read and left out."
    • addedOutput schema / properties / per_source / items / properties / source / description
      Added value: +"The catalogue this row is about."
    • changedOutput schema / properties / per_source / items / properties / state / description
      Previous value: -"'answered' is a catalogue that looked, and a count of zero there means it found nothing. 'failed' could not answer. 'absent' was never asked. An answer holding rows from some catalogues is no evidence about the others."New value: +"'answered' looked, and a count of zero means it found nothing. 'failed' could not answer, and states nothing about what it holds. 'absent' was never asked. Only the first is evidence about the world."
    • addedOutput schema / properties / per_source / items / properties / unattributed / description
      Added value: +"Records it answered with while carrying none of what was asked about."
    • removedOutput schema / properties / query
      Removed value: -{
-  "type": "string"
-}
    • changedOutput schema / properties / result_count / description
      Previous value: -"Rows returned here. Counts are never added across catalogues."New value: +"How many rows this page carries."
    • changedOutput schema / properties / results / items / additionalProperties
      Previous value: -falseNew value: +{}
    • removedOutput schema / properties / results / items / properties / duration_seconds
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "number"
-    },
-    {
-      "type": "null"
-    }
-  ]
-}
    • addedOutput schema / properties / results / items / properties / id / description
      Added value: +"Written instance:uuid. The catalogue travels with the uuid."
    • removedOutput schema / properties / results / items / properties / performers
      Removed value: -{
-  "items": {
-    "type": "string"
-  },
-  "type": "array"
-}
    • removedOutput schema / properties / results / items / properties / release_date
      Removed value: -{
-  "anyOf": [
-    {
-      "additionalProperties": false,
-      "properties": {
-        "precision": {
-          "description": "How much of the date a cataloguer entered. A value recorded to the year carries no month and no day, and reading it as one would claim a precision nobody entered.",
-          "enum": [
-            "day",
-            "month",
-            "year"
-          ],
-          "type": "string"
-        },
-        "value": {
-          "description": "The date exactly as the catalogue publishes it.",
-          "type": "string"
-        }
-      },
-      "required": [
-        "value",
-        "precision"
-      ],
-      "type": "object"
-    },
-    {
-      "type": "null"
-    }
-  ]
-}
    • removedOutput schema / properties / results / items / properties / retrieved_at
      Removed value: -{
-  "description": "When this record came off the catalogue, ISO 8601.",
-  "type": "string"
-}
    • addedOutput schema / properties / results / items / properties / source_url / description
      Added value: +"The address it was read from. Credit the catalogue and link it."
    • removedOutput schema / properties / results / items / properties / status / description
      Removed value: -"'established' is a record the catalogue holds. 'merged' and 'deleted' are markers: the identifier resolves, and what comes back describes the record rather than the thing it once named."
    • changedOutput schema / properties / results / items / properties / status / enum
      Previous value: -[
-  "established",
-  "deleted",
-  "merged"
-]New value: +[
+  "established",
+  "merged",
+  "deleted"
+]
    • removedOutput schema / properties / results / items / properties / studio
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ]
-}
    • removedOutput schema / properties / results / items / properties / title
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ]
-}
    • changedOutput schema / properties / results / items / required
      Previous value: -[
-  "id",
-  "source",
-  "title",
-  "release_date",
-  "duration_seconds",
-  "studio",
-  "performers",
-  "status",
-  "retrieved_at",
-  "source_url"
-]New value: +[
+  "id",
+  "source",
+  "source_url",
+  "status"
+]
    • changedOutput schema / properties / window / description
      Previous value: -"The window this answer covers, per catalogue. An emptiness here is an emptiness inside that window."New value: +"The page a catalogue paged through, absent where none was given one."
    • changedOutput schema / required
      Previous value: -[
-  "results",
-  "result_count",
-  "ordering",
-  "per_source",
-  "notes"
-]New value: +[
+  "results",
+  "result_count",
+  "per_source",
+  "ordering",
+  "notes"
+]
  3. Changed10 schema fields changedv0.2.1
    • changedInput schema / properties / date_from / description
      Previous value: -"Earliest release date, as YYYY-MM-DD."New value: +"Released strictly after this date, as YYYY-MM-DD. A catalogue takes one date comparison at a time, so giving both bounds sends this one and reports the other as not received."
    • changedInput schema / properties / date_to / description
      Previous value: -"Latest release date, as YYYY-MM-DD."New value: +"Released strictly before this date, as YYYY-MM-DD."
    • addedInput schema / properties / match
      Added value: +{
+  "description": "How a list of identifiers reads. 'all' returns scenes carrying every one of them and is the default; 'any' returns scenes carrying at least one.",
+  "enum": [
+    "all",
+    "any"
+  ],
+  "type": "string"
+}
    • changedInput schema / properties / page / maximum
      Previous value: -9007199254740991New value: +10000
    • addedOutput schema / properties / cached
      Added value: +{
+  "description": "Present when the answer came from the in-memory store.",
+  "type": "boolean"
+}
    • addedOutput schema / properties / per_source / items / properties / skipped
      Added value: +{
+  "type": "number"
+}
    • addedOutput schema / properties / per_source / items / properties / unattributed
      Added value: +{
+  "type": "number"
+}
    • removedOutput schema / properties / query / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / query / type
      Added value: +"string"
    • changedOutput schema / required
      Previous value: -[
-  "query",
-  "results",
-  "result_count",
-  "ordering",
-  "per_source",
-  "notes"
-]New value: +[
+  "results",
+  "result_count",
+  "ordering",
+  "per_source",
+  "notes"
+]
  4. First observedv0.1.1

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to repeat safety. It adds valuable behavioral context: the per-catalogue response structure (failure, nobody asked, emptiness), the refusal of both paths, and the non-aggregation of counts. This goes beyond annotations, though it could mention pagination behavior more explicitly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded with the core purpose. It uses clear, structured language to explain the two paths and result semantics. However, some phrasing is slightly convoluted (e.g., 'an emptiness it established'), which could be clearer, but overall it's efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (16 parameters, multiple catalogues, exclusive paths), the description covers the essential behavioral aspects: the two paths, per-catalogue results, and non-aggregation. It doesn't detail every parameter, but the output schema exists and the description focuses on the most critical usage rules. It's adequate for an agent to use correctly, though more parameter-specific guidance would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 38%, so the description must compensate. It does explain key parameters like query, match, and limit, and clarifies the exclusive nature of query vs. typed arguments. However, many parameters (code, date, title, sources, direction, etc.) lack description-level detail, relying on schema names. The description adds meaning for the most complex interactions but not all.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches scenes across every configured stash-box catalogue, with two exclusive search paths. It distinguishes itself from sibling tools like search_performers, search_studios, and search_tags by specifying the resource (scenes) and the multi-catalogue scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly explains the two exclusive paths (query vs. typed arguments) and when to use each, noting that writing both is refused. It also clarifies that counts are never added across catalogues, guiding the agent on how to interpret results. This provides clear usage context and exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools