Skip to main content
Glama
KitchenSink4AI

io.github.nometalalchemist/kitchensink4xl

by KitchenSink4AI
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Local

set_filter

Apply autofilter criteria to an Excel range and hide non-matching rows, using header-based column references with AND logic. Safely backs up and verifies changes.

Instructions

Apply an autofilter over a range whose first row is the header, and actually hide the non-matching rows: an .xlsx stores filter CRITERIA, not hidden state, so criteria (a list of {column, op, value}, ops as in query_range, combined as AND) are evaluated here over cached and literal values; a row whose tested cell holds an uncalculated formula stays visible with a warning. A hazardous workbook refuses unless allow_loss is true. Auto-backup to .ks4xl-backups; atomic verified save. Refuses while open in Excel.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pathYes
sheetNo
backupNo
criteriaNoAutofilter criteria, {column, op, value}, combined as AND. Rows that fail are actually hidden, since .xlsx stores criteria and not state.
locationYes
allow_lossNo
verify_comNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.2.0
    • changedOutput schema / (root)
      Previous value: -{
-  "additionalProperties": true,
-  "type": "object"
-}New value: +null
  2. Changed3 schema fields changedv1.1.0
    • changedInput schema / properties / criteria / anyOf
      Previous value: -[
-  {
-    "items": {},
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "properties": {
+        "column": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "minimum": 1,
+              "type": "integer"
+            }
+          ],
+          "description": "A column: a header name, a column letter, or a 1-based number."
+        },
+        "op": {
+          "enum": [
+            "eq",
+            "ne",
+            "gt",
+            "ge",
+            "lt",
+            "le",
+            "contains",
+            "startswith",
+            "endswith",
+            "regex",
+            "in",
+            "not_in",
+            "is_blank",
+            "not_blank"
+          ],
+          "type": "string"
+        },
+        "value": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "number"
+            },
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            },
+            {
+              "items": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "boolean"
+                  }
+                ]
+              },
+              "type": "array"
+            }
+          ],
+          "description": "the value to compare against; type follows the column"
+        }
+      },
+      "required": [
+        "column",
+        "op"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]
    • addedInput schema / properties / criteria / description
      Added value: +"Autofilter criteria, {column, op, value}, combined as AND. Rows that fail are actually hidden, since .xlsx stores criteria and not state."
    • addedInput schema / properties / location / anyOf
      Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "object"
+  }
+]
  3. First observedv1.0.0

TDQS

A4/5.0
Behavior5/5

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

With only readOnlyHint=false provided, the description carries the full burden of behavioral disclosure and does so richly. It explains cached/literal evaluation, formula rows staying visible with a warning, refusal of hazardous workbooks unless allow_loss=true, auto-backup with atomic verified save, and refusal while the workbook is open in Excel.

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

Conciseness5/5

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

The description is dense but tightly structured: the core behavior is front-loaded, followed by caveats and safety details. Each clause contributes non-obvious context, and nothing feels redundant or filler.

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

Completeness3/5

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

For a 7-parameter destructive write with no output schema, the description covers many non-obvious behaviors, from formula warnings to backup and Excel locking. However, it leaves the meaning of the required location parameter and the optional verify_com parameter unexplained, and it does not state what the tool returns, so some gaps remain.

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

Parameters2/5

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

Schema coverage is only 14%, and the required location parameter is essentially unexplained beyond its type union. The description adds useful meaning for criteria and allow_loss, but it does not clarify location, sheet, or verify_com, so it only partially compensates for the schema gap.

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 opens with a specific verb, resource, and outcome: 'Apply an autofilter over a range whose first row is the header, and actually hide the non-matching rows.' It clearly distinguishes the tool's behavior from related operations by emphasizing actual row-hiding, and it even references query_range for operator semantics.

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

Usage Guidelines3/5

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

The description implies the main use case: applying filter criteria and hiding rows because .xlsx stores criteria, not hidden state. However, it never explicitly says when to prefer set_filter over clear_filter or query_range, and it gives no when-not-to-use guidance.

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

Install Server

Other Tools