Skip to main content
Glama
KitchenSink4AI

io.github.nometalalchemist/kitchensink4xl

by KitchenSink4AI
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Set Filter

set_filter
DestructiveIdempotent

Apply autofilter criteria to an Excel range, hiding rows that don't match. Evaluates formulas and cached values, with safe backup and loss protection.

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.1/5.0
Behavior5/5

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

Even though annotations already mark the tool as destructive and idempotent, the description adds substantial behavioral context: uncalculated formulas keep rows visible with a warning, hazardous workbooks require allow_loss, backup and atomic verified save happen automatically, and the tool refuses while the workbook is open in Excel. No contradiction with annotations.

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 dense but information-rich, with the core action front-loaded. It is somewhat run-on, but virtually every clause carries distinct behavioral value, so the size is justified.

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?

For a destructive write operation with no output schema, the description covers side effects, safety conditionalities, persistence behavior, and an important lock condition. It falls short only by omitting return-value behavior and leaving some parameter semantics undefined.

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

Parameters3/5

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

Schema description coverage is very low (14%), so the description must compensate. It does clarify criteria structure, AND combination, ops, and the meaning of allow_loss and backup, but path, sheet, location, and verify_com remain unexplained. This is partial compensation with notable gaps.

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 first sentence names an exact action and resource: apply an autofilter over a range whose first row is the header. It also states the crucial behavior that non-matching rows are actually hidden, which distinguishes it from a criteria-only filter or from clear_filter.

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 gives clear context for what applying the filter does, but does not explicitly say when to choose this tool over alternatives like query_range, sort_range, or clear_filter. Refusal conditions and the auto-backup behavior help, but no when/when-not guidance is given.

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