Skip to main content
Glama
Sign In
agentflight

agentflight

by codesphere-u
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

agentflight_lint_tools

Read-onlyIdempotent

Statically inspects MCP tool schemas against 10 ergonomics rules, calculates an Agent Ergonomics Score, and returns actionable fixes for LLM tool-calling issues.

Instructions

Statically inspect MCP tool schema definitions against 10 ergonomics rules (TS001-TS010) and calculate an Agent Ergonomics Score.

Purpose

Evaluates Model Context Protocol tool schemas for anti-patterns that confuse LLM tool-calling (tautological descriptions, missing required arrays, ambiguous parameter types, unconstrained inputs, and lack of usage boundaries). Produces an ergonomics score (0-100) and actionable remediation steps.

When to use

  • Auditing and validating MCP tool definitions during development or CI/CD pre-commit hooks.

  • Benchmarking tool schema clarity and LLM tool selection readiness before deployment.

When NOT to use

  • Do NOT use to evaluate runtime agent trajectory recordings; use agentflight_diff_cassettes or agentflight_verify_cassette instead.

Behavior & Side Effects

  • Read-only: Operates purely in-memory; does not mutate any schemas or files.

  • Deterministic: Analyzes schemas through static AST and JSON Schema inspection with zero external network calls.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "tools": "<tools>"
    },
    "name": "agentflight_lint_tools"
  }
}

Input Schema

NameRequiredDescriptionDefault
toolsYesList of MCP tool definition objects containing name, description, and inputSchema to be statically analyzed.

Output Schema

NameRequiredDescriptionDefault
scoreYesAgent Ergonomics Score from 0 to 100.
passedYesTrue if score meets or exceeds the passing threshold (>= 80).
violationsYesList of detected tool smell violations across rules TS001 through TS010.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.1.1
    • changedInput schema / properties / tools / description
      Previous value: -"List of MCP tool schema objects to lint."New value: +"List of MCP tool definition objects containing name, description, and inputSchema to be statically analyzed."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "passed": {
+      "description": "True if score meets or exceeds the passing threshold (>= 80).",
+      "type": "boolean"
+    },
+    "score": {
+      "description": "Agent Ergonomics Score from 0 to 100.",
+      "type": "number"
+    },
+    "violations": {
+      "description": "List of detected tool smell violations across rules TS001 through TS010.",
+      "items": {
+        "properties": {
+          "message": {
+            "description": "Diagnosis and guidance on fixing the smell.",
+            "type": "string"
+          },
+          "rule_id": {
+            "description": "Ergonomics rule code (e.g. TS001).",
+            "type": "string"
+          },
+          "severity": {
+            "description": "Severity grade (error, warning, info).",
+            "type": "string"
+          },
+          "tool_name": {
+            "description": "Violating tool name.",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "score",
+    "passed",
+    "violations"
+  ],
+  "type": "object"
+}
  2. First observedv1.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnly, idempotent, closed-world, and non-destructive, but the description still adds real behavioral context: purely in-memory operation, deterministic static AST and JSON Schema inspection, and zero external network calls. That is value beyond the structured fields rather than a restatement of them.

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?

Front-loaded with the core action, then organized under Purpose / When to use / When NOT to use / Behavior headings, so an agent can scan to the relevant section. Mild redundancy between the opening sentence and the Purpose section, but no filler.

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

Completeness5/5

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

For a single-parameter, read-only analysis tool with full annotation coverage and an output schema, the description covers what is analyzed, what is produced, side effects, and routing to alternatives. Nothing needed to invoke it correctly is missing.

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 100% and the single 'tools' parameter is documented in the schema as a list of MCP tool objects with name, description, and inputSchema. The description mentions analyzing schemas but adds no shape, format, or batching detail beyond what the schema already says, so the baseline of 3 applies.

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?

States a specific verb and resource ('statically inspect MCP tool schema definitions'), names the exact rule set (TS001-TS010), and specifies the output artifact (Agent Ergonomics Score 0-100). It is clearly distinguishable from the sibling cassette tools, which operate on runtime recordings rather than static schemas.

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?

Provides explicit 'When to use' bullets (development audits, CI/CD pre-commit hooks, pre-deployment benchmarking) and an explicit 'When NOT to use' section that redirects to the named siblings agentflight_diff_cassettes and agentflight_verify_cassette. The boundary against the alternative tools is stated, not inferred.

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