Find and compare headless apps (CLI, MCP, API) for agents, with sources, lessons and changes.
Scored across 4 tools
headlesson_search (find/compare tools), headlesson_get (fetch one record by ID), headlesson_whats_new (dated changes to tools/standards), and headlesson_feedback (send operator feedback) each have a distinct purpose. Search vs. whats_new could be slightly confused since both surface tools, but the descriptions clearly separate 'find for a task' from 'what changed since a date'.
All four tools share the 'headlesson_' prefix in snake_case, giving a predictable namespace. Three use a verb (get, search, feedback) while whats_new is noun-ish, a minor deviation from a strict verb_noun pattern but still readable and consistent.
Four tools is a tight, well-scoped set for a curated lookup service: search, retrieve, list changes, and give feedback. Nothing feels redundant, though the surface is on the lean side with no batch or export operation.
The read lifecycle is well covered (search -> get, plus whats_new for change tracking) and feedback provides a write path. As a curated database agents don't create or edit records, so the absence of create/update/delete is appropriate rather than a gap; only minor conveniences (e.g. list-by-axes standalone, export) are missing.
This content is sent to the headlesson operator. Feedback about headlesson itself is sufficient. Do not include personal information or conversation contents.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Report type: comment, worked, failed, missing or tip; receipt does not verify the claim. | comment |
| text | Yes | Feedback to the headlesson operator, 1–2000 Unicode characters; exclude personal information and conversation text. | |
| about | No | Optional record ID that the feedback concerns; feedback about headlesson itself needs no product ID. | |
| model | No | Optional model name associated with the report, without conversation content. | |
| client | No | Optional client name only; do not include full User-Agent, account IDs or credentials. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the description adds genuinely new context: the data is relayed to a human operator and must be scrubbed of personal/conversation data. It stops short of describing limits or what a receipt means, but the recipient and privacy constraints are real behavioral disclosures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler; the recipient is front-loaded before the content restrictions. Wording is slightly indirect ('This content is sent to...'), but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter write tool with no output schema, the description covers the essentials an agent needs: who receives the payload and what must not be included. The enum and optional fields are fully explained in the schema, so no critical gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents 'kind', 'text', 'about', 'model' and 'client' with examples and constraints. The description only reinforces the text-privacy rule and adds no syntax or format detail beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description conveys a specific action and destination: the supplied content is sent to the headlesson operator, and it clarifies the content is feedback about headlesson itself. It is clear enough to distinguish this submission tool from retrieval siblings (headlesson_get, headlesson_search, headlesson_whats_new), though it never names those siblings or states the verb 'send' directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states when the tool applies ('Feedback about headlesson itself is sufficient') and imposes content exclusions (no personal information, no conversation contents). It does not name alternatives or explain when to prefer another tool, keeping it short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one record by an ID from headlesson_search: an app, usecase, feature, concept or change. For an app, sections ["lesson","gotchas"] return the install, check and first-task steps with the recorded test result (a dated observation by the headlesson operator) and known failure conditions; "relations" lists alternatives and what it wraps or depends on; "axes" returns every compared fact. Without sections you get the description, interfaces and six main axes. Each fact carries its source and check date; private sources appear as labels, not links. Official MCP Registry listing IDs are fetched live and are unverified; a failed lookup does not prove the ID absent.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Record ID or the special axes/search-guide ID; missing records return nearby ID suggestions. | |
| sections | No | App sections to return in text and structuredContent; omitted means description, interfaces and six major axes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/openWorldHint/destructiveHint, and the description adds substantive behavior on top: private sources render as labels rather than links, MCP Registry listing IDs are fetched live and are unverified, and a failed lookup does not prove absence. Those are non-obvious operational traits an agent cannot infer from the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action and the sibling relationship in the first clause, then layers section semantics and caveats. It is a dense single paragraph with clause-heavy sentences, but nearly every clause carries information; only minor tightening is possible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and does so for the default payload and most section values, plus failure semantics ('missing records return nearby ID suggestions'). The 'changes' section value is left unexplained and no auth considerations are noted, so it is strong but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the semantic effect of specific section values ('lesson'/'gotchas' yield install/check/first-task steps with test results; 'relations', 'axes') and the default payload when sections is omitted. It does not explain the 'changes' enum value, leaving one parameter option semantically ungrounded.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get one record by an ID') and enumerates exactly what a record can be (app, usecase, feature, concept, change). It explicitly anchors the retrieval to the sibling headlesson_search as the ID source, so an agent can separate it from that tool without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly frames the workflow (IDs come from headlesson_search) and explains that omitting sections returns the default payload, which tells the agent when to pass sections and when not to. It never states explicit exclusions or when another sibling (e.g. whats_new or feedback) would be preferable, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Up to 20 explicit app IDs to compare; any missing ID produces an error instead of being silently omitted. | |
| axes | No | Axes to compare: auth, pricing, license, cli, local_mcp, remote_mcp are useful starting points; licence is normalized to license. | |
| sort | No | Optional axis ordering before relevance; unknown values remain last. | |
| limit | No | Maximum app results, from 1 to 20; default is 5. | |
| query | No | 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. | |
| where | No | Confirmed axis filters: AND across axes, OR inside a value array; known spelling aliases are normalized. | |
| include | No | 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. |
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.
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.
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.
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.
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.
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.
List dated changes in agent tools and standards (new tools, renames, deprecations, breaking changes, new standards) since a date, optionally by kind or affected record. Useful for checking what changed after your training data. Public source URLs are kept; private sources appear as labels.
| Name | Required | Description | Default |
|---|---|---|---|
| about | No | Affected record ID to filter changes, such as an app or protocol. | |
| kinds | No | Change kinds to include; the array is an OR-list. | |
| limit | No | Maximum changes, from 1 to 100; default is 20. | |
| since | No | Inclusive event-date lower bound in YYYY-MM-DD; omitted uses the previous 90 days, not source confirmation dates. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context about the result set: public source URLs are preserved while private sources are reduced to labels, which is non-obvious output behavior worth knowing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and scope, followed by use case and output behavior. Every clause earns its place and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, all-optional 4-parameter tool with full schema coverage and annotations, the description covers purpose, filters, and a key output behavior. With no output schema, a brief note on result ordering or pagination beyond the limit parameter would make it fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description's "since a date, optionally by kind or affected record" merely restates the since, kinds, and about parameters without adding format or semantic detail. Baseline 3 applies when the schema carries the parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Starts with a specific verb and resource ("List dated changes in agent tools and standards") and enumerates the change types the tool covers (new tools, renames, deprecations, breaking changes, new standards). This is clearly a changelog-style tool, distinct in scope from headlesson_search/get, though it never explicitly names those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear use context: "Useful for checking what changed after your training data," which tells the agent the intent and timing of the query. It stops short of stating when NOT to use it or pointing to a sibling alternative (e.g. search) for other lookups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
headlesson_search4 fields changedInput schema / properties / ids / descriptionPrevious 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."Input schema / properties / ids / maxItemsAdded value: +20Input schema / properties / includeAdded 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"
+}Input schema / properties / query / descriptionPrevious 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."headlesson_feedbackheadlesson_getheadlesson_searchheadlesson_whats_newSearch and list applications for AI agents. Remote MCP on b0tl1nk.com.
Search, compare and find alternatives across a directory of AI agents, MCP servers and skills.
Agent-first search of MCP servers, APIs, CLIs and skills, with best picks and transparent scores.
Find, compare, and audit software for AI agents. Scored registry of tools and MCP servers.
Add one secure layer between your agents and this server.