Skip to main content
Glama
Sign In

headlesson

by com.headlesson
OverviewDiscussionsAdmin

Find tested tools for a task

headlesson_search
Read-only

Find command-line tools, MCP servers and APIs for a task, and compare them. Ask in plain English or Japanese ("extract text from scanned PDFs") or by product name. Each result gives an ID, a one-line reason it matches, and when it was checked. Pass the ID to headlesson_get with sections ["lesson","gotchas"] to get the steps (install, check, first task) with their recorded test result (most were run by an agent; a few are untested) and known failure conditions, such as a tool that exits 0 with empty or wrong output. Filter or compare with axes such as auth, pricing, license and remote_mcp (where, axes, ids). Curated records come first. If none match, or include:["registry"] is set, one public word from the query is looked up in the Official MCP Registry; those listings are unverified (what is sent is described on the query field).

Input Schema

NameRequiredDescriptionDefault
idsNoUp to 20 explicit app IDs to compare; any missing ID produces an error instead of being silently omitted.
axesNoAxes to compare: auth, pricing, license, cli, local_mcp, remote_mcp are useful starting points; licence is normalized to license.
sortNoOptional axis ordering before relevance; unknown values remain last.
limitNoMaximum app results, from 1 to 20; default is 5.
queryNoTask or product name in English or Japanese. External Registry lookup sends only one ASCII public name fragment (longest significant ASCII word from free text, or a supplied namespace; max 200 chars) when curated matches are absent or include registry is requested; the full free text is not sent. Recognized credential/URL/PII patterns are skipped; this is not a complete secret filter. Do not include secrets.
whereNoConfirmed axis filters: AND across axes, OR inside a value array; known spelling aliases are normalized.
includeNoExplicitly request the supplemental Official Registry name lookup alongside curated results. Otherwise it is attempted only when curated matches are absent. At most five unverified listings; one-page comparison only.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • changedInput schema / properties / ids / description
      Previous value: -"Explicit app IDs to compare; any missing ID produces an error instead of being silently omitted."New value: +"Up to 20 explicit app IDs to compare; any missing ID produces an error instead of being silently omitted."
    • addedInput schema / properties / ids / maxItems
      Added value: +20
    • addedInput schema / properties / include
      Added value: +{
+  "description": "Explicitly request the supplemental Official Registry name lookup alongside curated results. Otherwise it is attempted only when curated matches are absent. At most five unverified listings; one-page comparison only.",
+  "examples": [
+    [
+      "registry"
+    ]
+  ],
+  "items": {
+    "const": "registry",
+    "type": "string"
+  },
+  "type": "array"
+}
    • changedInput schema / properties / query / description
      Previous value: -"Task or product name in English or Japanese; common request words are ignored."New value: +"Task or product name in English or Japanese. External Registry lookup sends only one ASCII public name fragment (longest significant ASCII word from free text, or a supplied namespace; max 200 chars) when curated matches are absent or include registry is requested; the full free text is not sent. Recognized credential/URL/PII patterns are skipped; this is not a complete secret filter. Do not include secrets."
  2. First observed

TDQS

A4.4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so scope and safety are partly covered. The description still adds real behavioral context: result shape, curated records first, unverified Registry listings capped at five with one-page comparison, and unsent-field privacy behavior. However, these are largely restatements of what the very detailed schema descriptions already convey, so it adds less beyond structured fields than the initial read suggests.

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 purpose, then workflow, then edge cases. It is dense and parenthetical-heavy, with some clauses competing for attention, but each sentence carries information an agent needs rather than 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?

No output schema exists, and the description compensates by describing the return shape (ID, one-line match reason, checked timestamp) plus the downstream handoff to headlesson_get. For a 7-parameter, nested-object, open-world search tool, nothing required to call it correctly is missing.

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 coverage is 100%, so the baseline is 3. The description goes further by framing axes as a compare/filter mechanism and explaining the curated-first vs. registry-include behavior that ties several parameters together, adding semantic glue beyond individual parameter docs.

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+resource+scope: 'Find command-line tools, MCP servers and APIs for a task, and compare them.' It also names the natural sibling in the workflow (headlesson_get) and distinguishes the search/get split, so an agent can place it without opening the schema.

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?

Explicit about input modes (plain English or Japanese, or product name), about filtering/comparing via axes, and about the follow-up call: 'Pass the ID to headlesson_get with sections ["lesson","gotchas"]'. It also states the fallback condition that triggers Registry lookup.

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

All headlesson toolsInspect
Try in Browser
Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources