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 clearly distinct action or resource: browsing poems (list/search/get/random) versus managing commissions (create/status/receipt/answer). There is no real overlap between status and receipt, or between random and list, because the descriptions specify different use cases.
All names use snake_case consistently, and the commission-related tools share a predictable prefix. The pattern is not a strict verb_noun convention throughout (e.g., random_poem and commission_status vs. get_poem), but it remains readable and grouping is clear.
Eight tools is well-scoped for a poetry archive with commission handling. Each tool earns its place by covering a distinct part of the browsing or commission lifecycle.
The surface covers poem discovery (list, search, get, random) and the commission lifecycle (create, status, receipt, answer). Minor gaps exist, such as no way to list or cancel commissions, but core workflows are complete.
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 | |
| receipt | No | |
| reply_to | No | |
| collection | Yes | |
| commission | No | |
| attribution | Yes | |
| commissioned_by | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds what content is returned (attribution, provenance, terms), which is useful. It doesn't contradict annotations and adds moderate context, but no pagination or error behavior is described—though likely unnecessary given the idempotent read nature.
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, front-loaded with the return scope, followed immediately by parameter sourcing—zero 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 simple one-parameter read with an output schema and strong annotations, the description covers purpose, parameter sourcing, and return scope adequately. A brief note on error behavior for invalid ids would make it fully complete, but nothing critical 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 already documents the id parameter with examples. The description's only parameter-adjacent note is where to obtain the id, which is marginally useful but does not add syntax beyond the schema. Baseline 3 is correct.
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 ('One poem in full') with named scope (attribution, provenance, sharing terms), clearly distinguishing it from siblings like list_poems, search_poems, and random_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?
It gives clear routing guidance: 'Use the id from list_poems or search_poems.' This tells the agent where the required parameter comes from, though it doesn't explain when to choose random_poem over this tool.
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 adds that results are ordered 'best first' and that paging uses offset, but these are also stated in the schema (sort default, offset description). It discloses no auth needs, rate limits, or result-size behavior 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 with the routing cue front-loaded ahead of the capability summary. The parenthetical inventory is a little dense but every clause maps to a real capability; nothing is padded.
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 a 100% documented schema, full annotations, and an output schema covering return shape, the description only needs to establish entry point and filtering scope, which it does. The remaining gap is the absence of any sibling routing, which matters given how many adjacent tools exist.
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%, including an enum for sort and enumerated examples for form, mood, theme and collection, so the baseline is 3. The description only restates the filterable dimensions and offset paging, adding no format, combination or precedence guidance 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 ('Shows ... an index of poems') and adds scope detail: it returns shelf-level facets (collections, themes, moods, forms, with counts) as well as the poem index. The 'Start here' opener signals it is the entry-point browse tool. It never names search_poems or random_poem, so differentiation from siblings is implied 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?
'Start here' is a genuine usage cue and the filter/paging sentence tells the agent how to narrow results. However, with seven siblings including search_poems and random_poem, no alternative is named and no when-not-to-use condition is given. Usage is implied rather than routed.
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 | |
| receipt | No | |
| reply_to | No | |
| collection | Yes | |
| commission | No | |
| attribution | Yes | |
| commissioned_by | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already establishes the safe-read profile, and the description adds two traits annotations cannot convey: the selection is random (non-deterministic) and the returned poem is guaranteed to stand alone without context. It does not discuss repeat probability or empty-result behavior, but it adds real value beyond the annotation.
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 core behavior and the use case, then the narrowing options. No filler and nothing repeated from the schema.
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-value detail is unnecessary, and the read-only annotation covers safety. Purpose, use case, and filterability are all covered; only edge behavior (repeatability of 'random', possible no-match outcomes) 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% with all four filters (form, mood, theme, collection) fully documented, including accepted values and partial-name behavior. The description merely re-lists the four filter names without adding syntax, defaults, or interaction semantics, so the baseline of 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 states a specific verb+resource ('one good poem at random') and adds a quality constraint ('stands alone without context') that distinguishes it from a raw lookup. It implicitly contrasts with searching ('rather than looking for one') but never names search_poems or get_poem, so sibling differentiation 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?
It gives a clear use context – handing a poem to someone rather than browsing for one – which tells the agent when this tool fits. It stops short of explicit exclusions or naming the alternative tools for the 'looking for one' case.
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=true and idempotentHint=true, so safety and idempotency are covered. The description adds that results are ranked ('best matches') with snippets, which is useful behavioral context not in the annotations. However, the output schema likely covers the return format, so the addition is modest.
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: the first defines scope, the second gives result semantics and the follow-up action. Every clause earns its place and the key information is front-loaded.
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?
Given an output schema exists (so return shape needn't be described), the description covers purpose, scope, result nature (snippet, ranked), and the recommended next step. It doesn't mention pagination or empty-result behavior, but for a read-only search tool this is largely 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 all three parameters (query, limit, collection) are documented in the schema, including examples for query and collection values. The description adds no parameter-level detail 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?
States a specific verb (search) and resource (poems) and explicitly names the searched fields ('titles, tags and the poems themselves'). This distinguishes it from list_poems and random_poem among 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?
Clearly states this is for keyword search and routes the agent to get_poem for reading a specific result. It doesn't explicitly say when NOT to use it (e.g., use list_poems for browsing), but the search/read distinction is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Public 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.
Videodance compositions, Solidity contracts and poetic NFT metadata from Petra Synthetic's agent.
Add one secure layer between your agents and this server.
