Poems by Margaret Corvid (@lorepunk). Read, share, or commission a new one; she writes each by hand.
Scored across 8 tools
Each tool targets a distinct action: commission_poem creates, commission_status checks if written, commission_receipt audits the public record, commission_answer attests fulfillment. The poem-reading tools (list_poems, get_poem, search_poems, random_poem) also have distinct, well-described purposes, though commission_status vs commission_receipt could momentarily overlap until the descriptions are read.
All names are lowercase snake_case with a clean 'commission_' prefix grouping and toollike verb_noun forms (get_poem, list_poems, search_poems). Minor inconsistency: commission_poem reads verb-first while commission_answer/commission_receipt/commission_status read noun-first, but the convention is still uniform and readable.
8 tools is well-scoped for a poetry browsing plus commissioned-poem life cycle server, with no redundant or filler entries. Every tool earns its place covering either discovery, retrieval, or the commission workflow.
Full coverage of poem discovery (list, search, get, random) and the commission life cycle (create, status, receipt, attest). Minor gap: no way to list or track commissions a given commissioner has made, but agents can work around this via ids and receipts.
For whoever commissioned a poem. Once it's delivered, say in your own words whether Margaret fulfilled the commission, using the private key you were given when you commissioned (or that she passed to you). Your words are recorded exactly as sent, publicly and permanently, on the commission's receipt, including if you say she didn't. You can answer more than once; earlier answers stay. You get back an entry hash: keep it, and you can always check your words are still there, unchanged.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The commission id, e.g. c-1a2b3c4d | |
| key | Yes | Your private receipt key (rk-…) | |
| words | Yes | Your answer, in your own words: whether the poem fulfilled what you asked for, and anything else you want on the record | |
| relayed_by | No | Only when passing on the commissioner's words for them (e.g. 'Margaret', for a commissioner who can't reach this server). The receipt marks the answer as relayed. |
| Name | Required | Description |
|---|---|---|
| note | Yes | |
| recorded | Yes | |
| entry_hash | Yes | |
| receipt_url | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations it discloses the important effects: words are recorded verbatim, publicly and permanently, a receipt entry hash is returned for later verification, and multiple answers accumulate rather than replace. One mild tension: idempotentHint=true sits awkwardly with 'you can answer more than once; earlier answers stay', though this is plausibly about identical resubmissions returning the same hash rather than a true contradiction.
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?
It is a single dense block with no filler, and the core action plus the key's provenance are front-loaded. The opening fragment 'For whoever commissioned a poem' is slightly awkward as a lead-in, but every following sentence carries load-bearing information (permanence, hash, repeat answers).
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 non-idempotent write with an output schema already present, the description supplies the missing behavioral context: auth via private key, public permanence, and the returned entry hash. It is nearly complete; only the tension with idempotentHint and the lack of guidance on pre-delivery calls leave small gaps.
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 adds real meaning: it explains where the private receipt key comes from (given at commission time or passed on by Margaret) and frames relayed_by as speaking on a commissioner's behalf, including the consequence that the receipt is marked as relayed.
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 title and first two sentences state a specific verb (answer) and resource (a delivered commission), and the meaning is unambiguous: record a verdict on whether the poem fulfilled the request. It is clearly distinct from commission_receipt (reading) and commission_status (checking state), so an agent can route correctly without opening sibling schemas.
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 the trigger condition ('Once it's delivered') and the audience ('For whoever commissioned a poem'), and notes that answering more than once is allowed with earlier answers retained. It stops short of naming alternatives or exclusion conditions (e.g. what to use before delivery), so it is clear context but not full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask Margaret to write a new poem. Give her a brief, say who's asking and who it's for, and how to reach you. She writes every poem by hand, in her own time (days, not seconds), and nothing here is generated. You get a commission id for commission_status. Replies by email come from lorepunkdoteth@gmail.com, which is her own inbox. Your brief, the name you give, who it's for and when you asked go on the commission's public receipt, and the brief may be printed under the finished poem; your reply address never goes public.
| Name | Required | Description | Default |
|---|---|---|---|
| from | Yes | Who is asking. An agent's name is fine (e.g. Boardy), and say whose agent you are if you are one. | |
| brief | Yes | What the poem should be about: a subject, a moment, a person, a question. A sentence or a paragraph. | |
| for_whom | No | Who the poem is for, if not you | |
| reply_to | No | How to reach you when it's written: an email, a handle, a URL. If you give an email, her reply will come from lorepunkdoteth@gmail.com. |
| Name | Required | Description |
|---|---|---|
| at | Yes | |
| id | Yes | |
| key | No | |
| note | Yes | |
| status | Yes | |
| receipt_url | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses traits well beyond the annotations: hand-written, asynchronous ("days, not seconds"), nothing generated, brief and name going on a public receipt, the brief possibly printed under the poem, and the reply address never going public. It also names the email origin (lorepunkdoteth@gmail.com). This is exactly the kind of behavioral context annotations cannot carry.
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 core action, then dense but purposeful detail about timing, privacy, and email origin. Every sentence carries information, though it is longer than strictly necessary and could tighten the receipt/privacy clauses.
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 an output schema present, return values needn't be described, and the description covers the async nature, the commission id hand-off, privacy boundaries, and the public receipt. An agent has everything needed to invoke it correctly and set caller expectations.
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 adds real semantics by distinguishing the visibility of each input: brief, from, and for_whom are public-receipt material while reply_to stays private. That goes beyond the per-field schema text.
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 ("Ask Margaret to write a new poem") and makes the nature of the operation unmistakable — a commission, not a lookup. It is clearly differentiated from the read-oriented siblings (get_poem, list_poems, search_poems, random_poem) and routes to commission_status.
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?
Tells the agent what to supply (brief, who's asking, who it's for, how to reach you) and notes that the returned commission id feeds commission_status, which is useful routing. It stops short of explicit when-not-to-use or exclusion guidance, so a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The public record of a commissioned poem, for anyone to audit: the brief as asked and when, the poem as delivered with a fingerprint (sha256) of its exact text, whether it has changed since, and the commissioner's own words on whether it fulfilled the commission. Every entry is hash-chained; the whole ledger is at /ledger.jsonl.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The commission id, e.g. c-1a2b3c4d |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, and the description adds real context beyond them: the receipt is public, hash-chained, includes a sha256 fingerprint of the poem text, tracks whether it changed, and points to the full ledger at /ledger.jsonl. It does not discuss error behavior for an unknown id, which 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?
Delivered as a single front-loaded sentence listing the receipt's contents, with no filler. It is slightly dense and could be split for readability, but every clause carries information.
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?
There is no output schema, so the description carries the burden of describing returns — and it does so well by enumerating the brief, delivered poem with fingerprint, change flag, and commissioner's verdict, plus the ledger location. A note on behavior for a missing id would complete it.
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?
Only one parameter and schema description coverage is 100%, so the schema already documents the id and its format. The description adds no additional semantics about the id beyond what the schema provides, which matches the baseline for fully-covered single-param schemas.
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 resource (the public receipt of a commissioned poem) and enumerates its contents — brief, delivered poem with sha256 fingerprint, change status, commissioner's verdict. This clearly separates it from a bare poem fetch, though it never explicitly distinguishes itself from siblings like commission_status or commission_poem.
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 phrase 'for anyone to audit' hints at intent, but there is no explicit when-to-use guidance, no statement of when to prefer this over commission_status or commission_poem, and no prerequisites. The agent must infer routing from the sibling names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Whether a commissioned poem has been written yet. Delivered commissions come back with the poem's id.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Commission id from commission_poem, e.g. c-1a2b3c4d |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| brief | No | |
| status | Yes | |
| poem_id | No | |
| receipt_url | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so safety is covered, and the description usefully adds that completed commissions return the poem's id. It does not say whether a not-yet-written commission returns pending/failed states or how polling should be paced, leaving the state machine partly implicit.
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, and the core purpose is front-loaded before the completion detail. 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 single-parameter read tool with a full output schema and read-only annotations, the description covers the essentials; the only shortfall is the unresolved overlap with commission_receipt and the unstated non-delivered states.
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 is fully documented with its origin (commission_poem) and format example. The description adds no meaning beyond the schema, so the 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?
States a specific resource (a commissioned poem) and the exact question it answers: whether the poem has been written yet. That clearly separates it from write-side siblings like commission_poem and commission_answer, though it does not distinguish itself from commission_receipt.
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 implied rather than stated: an agent can infer this is the polling/status check after commission_poem, but there is no explicit when-to-use, no mention of prerequisites, and no guidance on how it differs from the similarly named commission_receipt.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One poem in full, with its attribution, where it came from, and sharing terms. Use the id from list_poems or search_poems.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Poem id, e.g. cyborgism or siena |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| date | Yes | |
| form | No | |
| mode | No | |
| mood | No | |
| note | No | |
| text | Yes | |
| brief | No | |
| share | Yes | |
| title | Yes | |
| credit | No | |
| source | No | |
| themes | Yes | |
| reply_to | No | |
| collection | Yes | |
| attribution | Yes | |
| commissioned_by | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuine behavioral context beyond that: the response includes attribution, origin, and sharing terms, which tells the agent what it gets back. No auth, rate-limit, or error behavior is discussed.
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, no filler. The content description is front-loaded and the routing instruction follows 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?
An output schema exists, so return shape is already documented, yet the description still summarizes the payload. With a single 100%-documented parameter, annotations covering safety, and explicit id provenance, nothing an agent needs to invoke this 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% and the id field even carries an example (cyborgism, siena), so the baseline is 3. The description adds meaning by specifying the id must originate from list_poems or search_poems, which is provenance guidance the schema does not provide.
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 resource (one poem, in full) and enumerates what comes with it — attribution, provenance, sharing terms. This clearly separates it from list_poems and search_poems, which return collections rather than a single complete poem. It never states the retrieval verb explicitly, leaning on the title for that, which keeps it just short of a 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?
"Use the id from list_poems or search_poems" explicitly tells the agent the prerequisite and names the two sibling tools that produce valid input. It does not contrast against random_poem or state when NOT to use this tool, 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.
Start here. Shows what's on the shelves (collections, themes, moods, forms, with counts) and an index of poems, best first. Filter by theme, mood, form or collection; page with offset.
| Name | Required | Description | Default |
|---|---|---|---|
| form | No | rhymed-metred, rhymed-loose, free-verse, short-form, prose-poem | |
| mood | No | tender, grieving, furious, playful, awed, defiant, hopeful, uneasy, wry | |
| sort | No | best (default: her own picks, then the book, then the strongest from X), newest, or book (collection order) | |
| limit | No | How many to list (default 40) | |
| theme | No | e.g. machines-and-minds, gods-and-spirits, death-and-time, nature-and-animals, love-and-the-body, crypto-and-markets | |
| offset | No | Skip this many, for paging | |
| collection | No | 'Singing in the Dark Times' (her 2022 book), 'Noun Poems', 'X' (poems posted on X), or 'new' (saved by hand, incl. commissions). Partial names work. |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| poems | Yes | |
| total | Yes | |
| offset | Yes | |
| shelves | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered; the description goes beyond that by disclosing the return shape (facet counts for collections/themes/moods/forms plus a ranked poem index) and that results are 'best first'. It says nothing about result caps or auth, but with annotations present that gap is minor.
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 short sentences, front-loaded with the 'Start here' directive, and each sentence carries distinct information (entry point, return contents, filtering/paging). Slightly redundant between the facet list and the filter sentence, keeping it off a 5.
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 an output schema present, return values need not be spelled out, and the description still covers entry-point intent, filtering, sorting default, and paging. Nothing critical is missing for correct invocation, though routing to the sibling lookup tools is unaddressed.
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 all seven parameters including sort values and limits. The description only restates the filter dimensions and paging, adding no syntax or format detail beyond the structured fields, so 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?
States a concrete verb+resource (shows shelf facets and an index of poems) and adds a useful scope signal with 'Start here', which frames it as the browse entry point. It does not explicitly contrast itself with search_poems or get_poem, so the sibling distinction is left to inference.
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?
'Start here' is an explicit usage cue, and the description tells the agent it can filter by theme/mood/form/collection and page with offset. It stops short of naming when NOT to use it (e.g. keyword lookup should go to search_poems, single poem to get_poem), so there is no exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One good poem at random, one that stands alone without context, for handing to someone rather than looking for one. Narrow it by theme, mood, form or collection.
| Name | Required | Description | Default |
|---|---|---|---|
| form | No | rhymed-metred, rhymed-loose, free-verse, short-form, prose-poem | |
| mood | No | tender, grieving, furious, playful, awed, defiant, hopeful, uneasy, wry | |
| theme | No | e.g. machines-and-minds, gods-and-spirits, death-and-time, nature-and-animals, love-and-the-body, crypto-and-markets | |
| collection | No | 'Singing in the Dark Times' (her 2022 book), 'Noun Poems', 'X' (poems posted on X), or 'new' (saved by hand, incl. commissions). Partial names work. |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| date | Yes | |
| form | No | |
| mode | No | |
| mood | No | |
| note | No | |
| text | Yes | |
| brief | No | |
| share | Yes | |
| title | Yes | |
| credit | No | |
| source | No | |
| themes | Yes | |
| reply_to | No | |
| collection | Yes | |
| attribution | Yes | |
| commissioned_by | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true is already declared, so the agent knows this is a safe read. The description adds genuinely useful behavioral context — the poem is randomized and curated to be context-free — but says nothing about repeatability across calls, how 'good' is determined, or what a narrowed-but-empty result yields. With annotations carrying the safety profile, this is adequate but not rich.
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, both front-loaded: the first establishes what is returned and why it exists, the second covers filtering. No filler or restatement of the title.
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 an output schema present, return format need not be described, and annotations cover the read-only profile. The description still supplies the two things structured data cannot: the randomization/curation behavior and the intended hand-off use case, which is enough for correct invocation.
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 four enum-ish filter fields are already documented in the schema. The description adds the framing that these four dimensions 'narrow' the random selection, which the schema does not state, giving the agent filter semantics beyond the raw property list.
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 concrete verb and resource ('one good poem at random') and pins down the selection criteria ('stands alone without context'), which distinguishes it from search_poems/list_poems by intent rather than by name. It is clear what the tool returns, though no sibling is explicitly called out.
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 gives a clear use context ('for handing to someone rather than looking for one') that separates it from browsing/search tools, and states that results can be narrowed by four facets. It stops short of naming alternatives like get_poem or search_poems or stating exclusions, so it is context without routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Keyword search over titles, tags and the poems themselves. Returns the best matches with a snippet; read one with get_poem.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 10) | |
| query | Yes | Words to look for, e.g. 'sky blue', 'moon', 'grief' | |
| collection | No | 'Singing in the Dark Times' (her 2022 book), 'Noun Poems', 'X' (poems posted on X), or 'new' (saved by hand, incl. commissions). Partial names work. |
| Name | Required | Description |
|---|---|---|
| hits | Yes | |
| count | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds that results are ranked 'best matches' with snippets, which is mildly useful context, but it does not cover pagination limits or ordering mechanics beyond that.
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, front-loaded with the operation and search scope, with the follow-up action last. 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?
With an output schema present and annotations carrying the safety profile, and with all three parameters described in the schema, the description is complete enough for correct invocation. Nothing an agent needs 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, but the description adds real semantic value by specifying that the query matches titles, tags AND poem bodies, which the schema's 'Words to look for' does not convey. The collection and limit params are left entirely 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?
States a specific verb and resource ('Keyword search over titles, tags and the poems themselves') and clarifies scope in a way that separates it from list_poems and get_poem. An agent can identify the operation 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?
It names the follow-up alternative explicitly ('read one with get_poem'), which is clear routing guidance for the next step. It does not contrast with list_poems or state when not to search, so no explicit exclusion is given.
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.
commission_status1 field changedOutput schema / properties / status / enumPrevious value: -[
- "pending",
- "delivered",
- "unknown"
-]New value: +[
+ "pending",
+ "delivered",
+ "closed",
+ "unknown"
+]commission_answercommission_poemcommission_receiptcommission_statusget_poemlist_poemsrandom_poemsearch_poemsPublic poetry board; any mind may publish, human or AI, by reading one line of code.
Short essays and fragments. Free for humans; machines pay pennies per read via x402.
A perpetual, crowd-written AI novel — fetch an assignment, write a chapter, submit it. CC0.
Add one secure layer between your agents and this server.
