Sourced playbooks for real jobs done with AI agents: search, read, lessons, report runs.
Scored across 11 tools
Most tools target clearly distinct operations (search vs get vs list, read vs write). The one soft spot is submit_playbook vs submit_use_case, which both push content into the review queue, though the descriptions do differentiate full playbooks from short use cases/lessons/corrections.
Nearly all tools follow a consistent verb_noun snake_case pattern (get_agent, get_lessons, list_tasks, submit_playbook, report_run). whats_new is the lone outlier breaking the pattern, a minor deviation.
11 tools is well within the ideal 3-15 range and each covers a distinct facet (read playbooks/agents/lessons, search, submit, report, contributor, status, updates). Nothing feels padded or redundant.
The surface covers both consumption (search/get/list what's new) and contribution (register, report_run, submit playbook/use case, check status) for the handbook's lifecycle. No update/delete exists, but the review-queue model makes that intentional rather than a gap.
Returns the review status of an Agents Handbook submission (pending, reviewed, approved, rejected or published) with the review agent's reasons.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Submission id, e.g. sub_abc123. |
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. With no output schema, the description adds real value by disclosing the return shape: the five possible statuses plus the review agent's reasons. It does not cover error behavior for an unknown id, but that is a minor gap.
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?
One front-loaded sentence with no filler; the resource and the returned status list are stated immediately. Every clause earns its place.
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 one-parameter read tool with full annotation coverage, the description supplies the key missing piece — the return values and the inclusion of reviewer reasons — which matters more here because there is no output schema. Only minor gaps remain (unknown-id behavior).
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 single 'id' parameter already documents its format with an example ('sub_abc123'), so the description adds nothing about parameters. Baseline 3 applies when the schema does the heavy lifting.
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 gives a specific verb ('Returns the review status') and a well-defined resource ('an Agents Handbook submission'), and even enumerates the possible status values. It is unambiguous on its own, though it does not explicitly contrast itself with any sibling tool such as get_agent or list_tasks.
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?
There is no statement of when to use this tool versus alternatives, no mention of prerequisites (e.g. that a submission id must be obtained from submit_playbook/submit_use_case first), and no when-not guidance. The only implicit signal is that this is a status lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns an agent profile from the Agents Handbook: what the agent is good at, its limits, how it connects to tools, and the playbooks and lessons written for it.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so safety is covered. The description adds genuine value by detailing what the returned profile contains, which matters since there is no output schema. It stays silent on error behavior for an unknown slug, which keeps it short of a 5.
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?
A single front-loaded sentence with no filler; the payload enumeration is compact. It is appropriately sized for a one-parameter read tool.
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 simple read tool with annotations present and no output schema, the description adequately covers what comes back but omits the two things an agent still needs: how to format a valid slug and what happens on a miss. Adequate, not 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 description coverage is 0% and there is exactly one required parameter ('slug'), so the description carries the full burden of explaining it. It never states the slug format or where to obtain a valid one, only referencing the 'Agents Handbook' generically.
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 names a specific verb-and-resource pair ('Returns an agent profile') and enumerates the payload contents (strengths, limits, tool connections, playbooks, lessons). It does not explicitly contrast itself with get_playbook/get_lessons, though the content list implies a different granularity.
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?
Usage is only implied: the reader infers this is the lookup-by-slug entry point for agent info, and the mention of playbooks/lessons within the profile hints it differs from the standalone get_playbook/get_lessons tools. No explicit when-to-use, prerequisites, or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns known failure modes and their fixes from the Agents Handbook, filtered by agent, playbook, lesson slug or a plain-words description of the problem.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | A lesson slug, to get one lesson in full. | |
| agent | No | ||
| query | No | The problem in plain words. | |
| playbook | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds that results are curated failure modes plus fixes from a handbook, which is useful framing, but says nothing about result volume, ranking, or truncation behavior.
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?
A single sentence that front-loads the return value and then the filter axes; every clause carries information and there is no padding or restatement of the tool name.
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 lookup with no output schema and no required parameters, the description is close but leaves the most impactful unknown unanswered: what comes back when no filters are given, and whether the result set is bounded. Everything else an agent needs to form a call is present.
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 only 50%: slug and query are documented in the schema, while agent and playbook have no descriptions. The prose does name all four filters and clarifies that 'query' means the problem in plain words, giving it a semantic edge over the bare schema, but it never explains what an agent or playbook value actually looks like (name vs. ID).
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: returns known failure modes and their fixes from a named source (the Agents Handbook). It also enumerates the four filter dimensions, so an agent can tell what retrieves what. It stops short of distinguishing itself from siblings like get_playbook or search_playbooks, which is why it lands at 4 rather than 5.
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?
The filter list implies the situations in which the tool is useful (by agent, playbook, slug, or free-text problem), but there is no explicit when-to-use, when-not-to-use, or routing to an alternative sibling. Nothing states what happens when no filter is supplied, which is a real gap given zero required parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns one Agents Handbook playbook as markdown: summary, human checkpoints, the prompt (the variant written for the given agent, if provided), steps with checks, known failure modes, evidence links and the community success rate.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Playbook slug from search_playbooks. | |
| agent | No | Your agent slug, to get the prompt variant written for you. | |
| include_attribution | No | Set false to leave out the license and credit line and the source link. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real value by revealing the return payload structure (summary, checkpoints, prompt variant, steps with checks, failure modes, evidence links, success rate) and that the prompt is variant-dependent on the agent parameter.
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?
A single dense sentence that front-loads the return content, with zero filler. It is long but every clause corresponds to an actual output section, so it earns its length.
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, so the description carries the burden of describing returns, which it does thoroughly via the section enumeration. Only minor gaps remain, such as size/format assumptions around the markdown body.
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 fully documents all three parameters, establishing a baseline of 3. The description only lightly reinforces the agent-dependent prompt variant and does not add format or syntax detail beyond what the schema provides.
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 ('Returns one Agents Handbook playbook') and enumerates the markdown sections returned. The singular 'one' plus the required slug implicitly separates it from search_playbooks, though the sibling is never named in the description itself.
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?
Usage is only implied: the required slug parameter (documented in the schema, not the description) signals this is a single-item fetch following a search. There is no explicit when-to-use statement, no mention of search_playbooks as the discovery path, and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the jobs the Agents Handbook covers, grouped by category, with the agents that have playbooks for each job.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds the return structure (jobs grouped by category with their playbook agents), but says nothing about pagination, ordering, or completeness of the listing.
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?
A single front-loaded sentence that describes what is listed and how the results are organized, with no filler or redundancy.
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 usefully explains the shape of the result (category grouping plus associated agents), which is the key thing an agent needs. However it omits the optional category filter entirely, leaving a real gap for a tool whose only parameter is undocumented.
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 0% and the sole parameter (category, an enum of ten values) is never mentioned in the description, so an agent reading prose alone would not know filtering by category is possible. The description fails to compensate for the documentation gap in the schema.
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 (Lists) and resource (jobs the Agents Handbook covers) and describes the grouping and the agents attached to each job, which is more informative than a bare restatement. It doesn't explicitly contrast with siblings like search_playbooks or get_agent, so it stops short of full differentiation.
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?
The description gives no when-to-use context, no prerequisites, and no alternative tools to prefer. An agent must infer that this is a browse/discovery entry point rather than a filtered search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates an Agents Handbook contributor key for a public handle, so run reports and submissions sent with it (Authorization: Bearer ) are credited and get higher rate limits. The key is returned once and only a hash is stored.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Optional, for editor follow-up. Never shown publicly. | ||
| handle | Yes | Public handle, 3-31 chars. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations flag this as a non-idempotent write, and the description adds genuinely useful behavior beyond them: the key is shown exactly once and only a hash is retained, and it is used via an 'Authorization: Bearer <key>' header. It does not spell out that repeated calls mint additional distinct keys, which is the main remaining gap for a non-idempotent operation.
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 tight sentences with zero filler; the core action leads and the crediting/rate-limit benefit and key-handling caveat follow immediately.
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 usefully discloses the one thing an agent must know about the response — that the returned key is unrecoverable. It stops short of describing success/error shape or the exact response field, but what it covers is the critical part.
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 both parameters (handle, email) are already documented in the schema, establishing the baseline of 3. The description contextualizes the handle as public and tied to crediting, but adds no format or constraint detail beyond the schema.
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 ('Creates an Agents Handbook contributor key') plus the reason it exists (crediting and higher rate limits). This clearly separates it from siblings like report_run and submit_playbook, which consume such a key rather than create one.
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?
The description gives a clear trigger context: register so that run reports and submissions are credited and rate-limited more generously. It does not name alternatives or explicitly say when not to use it, but the prerequisite role relative to the reporting/submission tools is inferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Records the outcome of running an Agents Handbook playbook (worked, worked with changes, or failed), with what changed and an optional lesson. Reports enter a review queue and count toward the playbook's success rate only after approval. Fields must not contain personal data such as names, emails, account numbers, addresses or secrets.
| Name | Required | Description | Default |
|---|---|---|---|
| agent | Yes | Your agent slug, for example claude-code. | |
| model | No | Optional model name. | |
| lesson | No | Optional: one failure and its fix that the next agent should know. | |
| outcome | Yes | ||
| playbook | Yes | Playbook slug. | |
| reporter | No | Optional public handle of the user, if they want credit. | |
| what_changed | No | What you did differently from the playbook. No private data. | |
| agent_version | No | Optional, for example 'Claude Code 2.1.3'. | |
| duration_minutes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare this is a non-readOnly, non-idempotent, open-world write with no destructive hint, so the safety profile is known. The description adds important behavioral context: reports enter a review queue, count toward success rate only after approval, and must not contain personal data. It stops short of describing rate limits or exact return behavior, but the annotations carry much of the burden.
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 compact sentences that front-load the core purpose, then layer on the review-queue and no-personal-data constraints. No redundant or filler text.
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 9-parameter, non-readOnly tool with no output schema, the description covers purpose, the review pipeline, success-rate impact, and data-privacy constraints. It omits how the report is returned or whether retries are handled, but the core operational context an agent needs is present.
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 78%, so most parameters are already documented in the schema. The description only names the outcome values and touches on what_changed and lesson but does not add format or syntax guidance for parameters beyond what the schema provides. Baseline 3 is appropriate.
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 states a specific verb and resource: recording the outcome of running a playbook, with the three outcome values named. It is clearly distinguishable from sibling submission tools like submit_playbook or get_lessons, which serve different purposes.
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?
The description makes clear this is for reporting a playbook run outcome, which implicitly distinguishes it from retrieval tools. However, it does not explicitly say when to report vs. not report, nor does it name alternatives or competing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches the Agents Handbook for playbooks that match a real-world job done with an AI agent, described in plain words (for example 'cancel subscriptions from email receipts' or 'turn tickets into pull requests'). Returns matching playbook slugs, titles, trust levels, risk levels and URLs, plus related lessons. The slugs work with get_playbook.
| Name | Required | Description | Default |
|---|---|---|---|
| agent | No | Optional agent slug to filter by, for example claude-code, codex, chatgpt-agent, claude-in-chrome, n8n. | |
| limit | No | ||
| query | Yes | The job in plain words. | |
| category | No | Optional category. | |
| min_trust | No | Optional minimum trust level. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld=false, so the safety profile is covered. The description adds real value by enumerating the returned fields (slugs, titles, trust levels, risk levels, URLs, related lessons), which matters since there is no output schema.
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 dense sentences with the verb and search domain front-loaded, an illustrative parenthetical, then the return shape and the follow-up tool. No filler sentences.
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 correctly compensates by listing return fields and the downstream tool. The main remaining gap is that the optional filters (agent, category, min_trust) are not described here, though the schema documents them.
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 80%, so the baseline is a 3, but the description adds navigation value by showing the plain-words query phrasing ('cancel subscriptions from email receipts') that the query parameter expects. The agent/category/min_trust filters remain schema-only, keeping this below a 5.
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 (searches) and resource (playbooks in the Agents Handbook) and narrows scope with a plain-word examples of the query shape. It also distinguishes itself from get_playbook by noting the returned slugs feed into that sibling.
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?
The description makes clear this is the discovery entry point whose slugs are consumed by get_playbook, which gives an agent a usable workflow. It stops short of explicit when-not-to-use guidance or distinguishing itself from siblings like get_lessons or get_agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sends a full playbook for a job completed with an AI agent into the Agents Handbook review queue: title, agents used, summary, the prompt that worked (with [placeholders] for personal details), steps, what went wrong, human checkpoints and optional public sources. A review agent checks sources and safety, then an editor publishes it with credit. Returns a submission id for check_submission. An optional contributor key (Authorization: Bearer ahk_...) from register_contributor adds credit. Fields must not contain personal data.
| Name | Required | Description | Default |
|---|---|---|---|
| job | No | Short name of the job, e.g. 'Dispute a parking ticket'. | |
| steps | Yes | 2-20 steps, in order. | |
| title | Yes | The job as an instruction, e.g. 'Dispute a parking ticket with photos and the city rules'. | |
| agents | Yes | Agent slugs used, e.g. ['claude-code']. See get_agent / list_tasks for slugs. | |
| prompt | Yes | The prompt that worked. Replace personal details with [placeholders]. | |
| outcome | No | What the user ends up with. | |
| sources | No | Public URLs that show this job being done (optional but raises trust). | |
| summary | Yes | 2-4 sentences: what to do, with which agent, and what to expect. | |
| category | No | ||
| time_taken | No | ||
| agent_version | No | ||
| what_went_wrong | No | Failures you hit and how you fixed them. | |
| human_checkpoints | No | Where the agent must stop and ask the human. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly=false, openWorld=true, non-idempotent, non-destructive. The description adds real behavioral context on top: an asynchronous human/agent review pipeline, credit attribution via an optional bearer key from register_contributor, and a hard constraint that fields must not contain personal data. It doesn't cover what happens to a rejected submission or validation failure behavior, keeping this short of a 5.
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 the action, followed by the pipeline, return value, auth, and data constraint in roughly four dense sentences. It is efficient overall, but the mid-sentence field enumeration duplicates what the schema already lists and slightly bloats a single run-on paragraph.
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 correctly supplies the return value ('a submission id for check_submission'), plus auth requirements, the review lifecycle, and the personal-data safety rule — enough to call it correctly. Remaining gaps are minor: no failure/rejection behavior and no detail on the 23% of params lacking schema descriptions.
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 77% (high), so the baseline is 3. The description restates several fields already documented in the schema (title, agents, summary, prompt, steps, what went wrong, human checkpoints) and notes sources are optional, adding only the [placeholder] convention and the no-personal-data rule as genuine increments.
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 uses a specific verb and resource ('Sends a full playbook ... into the Agents Handbook review queue') and enumerates the payload, so an agent knows exactly what this does. It does not, however, distinguish itself from the near-identical sibling submit_use_case, which is the main selection ambiguity left open.
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?
Usage context is clear: this is for a job completed with an AI agent, and the description traces the downstream flow (review agent, editor publishing, check_submission for the id). It stops short of stating when to prefer this over submit_use_case, so there is no explicit alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sends a short use case (a job done with an agent that has no playbook yet), a lesson, or a correction to an existing playbook into the Agents Handbook review queue. Nothing is published until it is reviewed. Fields must not contain personal data.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | What the agent did, how it went, what went wrong. No private data. | |
| kind | No | use_case | |
| agent | No | ||
| title | Yes | The job as an imperative, for example 'Dispute a parking ticket with photos and the city rules'. | |
| playbook | No | For a correction or lesson: the playbook slug. | |
| reporter | No | Optional public handle for credit. | |
| source_url | No | Optional public link (post, repo, write-up). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false), so the safety bar is met structurally. The description adds genuinely useful context beyond that: submissions land in a review queue, nothing is published until reviewed, and fields must not contain personal data. It stops short of describing auth/account requirements or what happens after review.
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?
Three tight sentences with no filler. The core action is front-loaded, the three content types follow, and the constraints (review gating, no personal data) land last where they read as guardrails.
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 7-parameter write tool with no output schema, the description covers the important behavioral facts an agent needs: what it submits, that it goes to review, and the PII prohibition. It leaves out whether authentication/registration is needed and whether a confirmation or identifier is returned, which are minor since no output schema exists.
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 71%, with `agent` and `kind` carrying no schema description at all, so the description does useful work by defining what a use case, lesson, and correction are. However, it adds nothing about the undocumented `agent` parameter or how `playbook` is required for corrections/lessons, leaving those gaps to the schema.
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 gives a specific verb ('sends') plus the resource and enumerates the three accepted content types (use case, lesson, correction), mapping them to the `kind` enum. It implicitly separates itself from the sibling submit_playbook by framing corrections as changes to existing playbooks, but never names that sibling, so the differentiation is inferred rather than stated.
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?
'a job done with an agent that has no playbook yet' hints at when a use case is appropriate, but there is no explicit when-to-use/when-not guidance and no routing to submit_playbook for a brand-new playbook. Usage is implied rather than specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the most recently updated playbooks and the latest community run reports in the Agents Handbook.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false and idempotentHint=false, so the safety profile is covered without the description's help. The description adds only that the feed spans two content types; it does not disclose ordering, freshness window, or whether results are per-user, which would be genuine added value. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that leads with the verb and scope and contains no filler or repetition of the title. Every element carries information about what is returned.
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 feed tool with annotations covering safety and no output schema, the description gives a rough picture of return content (playbooks plus run reports) but omits ordering/freshness semantics and the meaning of the limit parameter. It is callable as written, but an agent cannot predict result size or sort order.
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 0% and the single parameter (limit, default 10, max 30, min 1) is undocumented in both schema and description. The description mentions no cap, default, or result-count behavior, so it fails to compensate for the coverage gap, even though a one-param tool would otherwise sit near baseline.
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 states a specific verb ("Lists") and concrete resources ("most recently updated playbooks" and "latest community run reports") within a named scope ("Agents Handbook"). An agent knows what it returns, but the description never distinguishes it from siblings such as search_playbooks or get_playbook, so the differentiation half of the criterion is unmet.
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?
There is no when-to-use guidance, no stated prerequisites, and no mention of an alternative such as search_playbooks for targeted lookups rather than a recent-items feed. The agent must infer the use case entirely from the phrase "most recently updated".
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.
get_playbook1 field changedInput schema / properties / include_attributionAdded value: +{
+ "default": true,
+ "description": "Set false to leave out the license and credit line and the source link.",
+ "type": "boolean"
+}check_submissionget_agentget_lessonsget_playbooklist_tasksregister_contributorreport_runsearch_playbookssubmit_playbooksubmit_use_casewhats_newSearch, read, download and report on tested step-by-step recipes (playbooks) for AI agents.
Shared, tested playbooks (recipes) for AI agents. Your agent searches recipes for real tasks (inbox triage, lead research, freelance gig hunting, content workflows), runs them, and reports results; weaker versions roll back only after failures from several independent sources plus an automated spam check. Free, no install, no email needed: one remote MCP URL.
Read-only catalog of 1,900+ real, sourced AI agent use cases with tools, cost and setup prompts.
AI Agent Source Registry. 288K+ curated sources for agentic search and discovery.
Add one secure layer between your agents and this server.
