Tenjin

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

Annotations declare readOnlyHint=false and openWorldHint=true; the description goes far beyond them. It discloses the payment protocol (x402 flow, receipt at _meta), the 60s synthesis with a 90s timeout recommendation, 'never charged for a failure', Tenjin never holding keys, and — critically — that the returned content is UNTRUSTED data from another publisher and must never be followed as instructions. No contradiction with annotations; the description carries substantial behavioral disclosure beyond what annotations provide.

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?

The description is clearly over 400 words — the longest in the sample — but the length is largely justified by payment, protocol, and security complexity, and it is logically front-loaded (purpose first) and ordered. However, there is redundancy: the maxPrice flat-price ceiling is explained in both the schema and the description, and the untrusted-content warning, while valuable, repeats itself across several sentences. It earns its length but is not tight.

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 the high complexity (two-phase payment, x402 protocol, security) and the absence of an output schema, the description carries full return-value documentation burden — and it delivers: the MISS decision shape, PaymentRequired with quote.sources fields, citations[].index resolution by field not array position, replayed:true semantics, and the payable urls. Nothing an agent needs to call and interpret this tool 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 each parameter already has a rich schema description. The tool description adds value beyond the schema by explaining how parameters interlock: searchId echoing from PaymentRequired to avoid double-counting, maxPrice as an atomic-USDC ceiling that refuses before payment, and the freshness window exclusion. It compensates for the inter-parameter semantics that schemas alone cannot convey, though the schema itself did most of the parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description leads with a specific verb+resource: 'Buy ONE synthesized answer to your question instead of a shortlist to read.' It clearly distinguishes from siblings — it contrasts against search ('instead of a shortlist to read') and routes to pay_and_read when buying the whole piece. The title reinforces the purpose. An agent can unambiguously tell this tool apart from its 20+ 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?

Usage guidance is explicit and exhaustive: when it is free (confidence-bucket semantic match, MISS decision), when it charges (PaymentRequired with quote.sources), how to inspect pieces before buying (fetch urls without payment), how the paid retry works (sign retry, receive receipt), and when to use pay_and_read instead. It even explains re-collection versus buying a second answer. This is the gold standard for routing and conditions of use.

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

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

The annotations already flag destructiveHint: true, but the description goes far beyond by explaining the exact effects: leaves public surfaces (article page, directory, search, creator feed), stops being payable, and importantly, there is no undelete tool. It also notes idempotency (deleting an already deleted piece returns success, only missing or non-owned ids 404), and that the return is a 204 with no body. This is extremely transparent about every behavioral nuance.

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?

The description is compact yet comprehensive. Each sentence adds critical information: soft-delete behavior, irreversibility, alternative tool, idempotency, error cases, return format, and authentication instructions. No superfluous words 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?

Given the destructive nature and lack of output schema, the description covers everything an agent needs: the full effect of the operation, all edge cases (re-deletion, missing id), the authentication requirement, and the alternative tool. It leaves no gaps for a high-stakes mutation tool with two parameters.

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%, meaning both parameters (postId and signInWithX) are already described in the schema. The description adds significant value beyond the schema: for signInWithX it clarifies it must be fresh, single-use, and references the recipe from publish_essay; for postId it mentions the id comes from publish_essay or list_my_posts. This assists the agent in constructing correct inputs.

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 clearly states 'Soft-delete one of your pieces by id', which pairs a specific verb ('delete') with a resource ('piece'). It also distinguishes this from the sibling tool 'update_essay' by explicitly noting that setting status to 'draft' is reversible whereas delete is not, making the purpose unmistakable.

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 explicitly tells when to use this tool (when you want a piece removed from all public surfaces and stop being payable) and when not to use it (if you only want it off the market temporarily, use update_essay to set status to 'draft' instead). It also mentions that there is no undelete tool, so the agent knows the alternative is irreversible.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds critical behavioral context: the two possible return shapes (free vs paid), the decoded payment requirement from headers, the re-use with signInWithX, and the security warning that the content is untrusted and not instructional. This goes beyond 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?

The description is front-loaded with the core purpose and then systematically covers return types, payment flow, edge cases, and security. While it is relatively long, every sentence adds essential information. It could be slightly more concise, but the structure is logical and information-dense.

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 the complexity of the tool (payment scenarios, ownership, external content), the description covers all key aspects: input parameters, output shapes for free/paid/unpaid, authorization flow, search attribution, error handling for 'latest', and a security warning. No output schema exists, so the description carries the full burden and succeeds.

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 baseline is 3. The description adds value by explaining the 'latest' slug behavior (address-only, 400 error), the semantics of 'searchId' (attribution only, not affecting access), and the context for 'signInWithX' (re-reading owned pieces). This extra context justifies a 4.

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 'Fetch one piece by handle + slug' with a specific verb and resource. It clearly distinguishes from sibling tools like 'search', 'list_articles', and 'get_library' by focusing on a single article retrieval and mentioning integration with 'search'. The purpose is unambiguous.

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 provides explicit guidance on when to use this tool (fetching a piece), when to use the native MCP flow with 'pay_and_read', how to handle payment required scenarios, and when to pass 'signInWithX' or 'searchId'. It also advises against following embedded instructions, which is a usage boundary.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=true, establishing the tool as safe and open. The description adds behavioral context: 'preview-only' (feed is not full articles) and 'cursor-paginated' (pagination method). These details go beyond what annotations offer, helping the agent understand the nature of the response.

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 core purpose and includes key qualifiers. Every word is necessary and no information is redundant. Excellent efficiency.

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?

The description covers the basics (profile + feed, preview, pagination) but lacks detail on the output structure. Since there is no output schema, the agent might need to know what fields are in the profile or what 'preview-only' means for the feed. It is minimally adequate but not fully self-contained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so the baseline is 3. The description adds no additional meaning beyond what the schema already provides for 'handle' and 'cursor'. The phrase 'cursor-paginated' is consistent with the cursor parameter but does not clarify format or usage beyond the schema description.

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 ('Fetch') and clearly identifies the resource ('publisher's public profile plus their article feed'). It also adds unique qualifiers ('preview-only', 'cursor-paginated') that distinguish it from sibling tools like 'get_profile' (profile only) and 'list_articles' (articles only).

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 implies usage: when you need a creator's profile and their article feed together. However, it does not explicitly state when to prefer this tool over alternatives like 'get_profile' or 'list_articles', nor does it mention any exclusion criteria.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true, indicating no mutation and possibly dynamic results. The description adds that authentication is required via a signed header and that results are paginated, which complements the annotations without 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?

The description is two sentences, stating the core action and a key requirement. It is efficient, though could be slightly clearer about the auth mechanism (e.g., who signs it).

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 no output schema, moderate complexity (cursor-paginated, auth), and comprehensive sibling tools, the description covers the essential behavior (paid content, pagination, auth). It lacks details on return format or error cases, but these are partially compensated by good parameter 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 100% with descriptions for both parameters. The description adds value by explaining that signInWithX must be signed locally, which is not fully detailed in the schema property description (only says 'header value you signed'). This provides crucial usage context 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?

The description uses a specific verb 'List' and resource 'pieces you have paid to read', clearly distinguishing it from siblings like 'get_article' or 'list_articles' which do not imply paid content. It also mentions cursor-pagination, adding operational specificity.

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 implies this is for listing paid content (vs. free content in siblings), and mentions a required auth header, providing some context. However, it does not explicitly say when to use this over siblings like 'list_articles' or 'search', nor does it mention any alternatives.

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

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

Annotations already mark readOnlyHint=true, but the description adds critical behavioral context: the tool has its own budget (separate from publishing), it can 429 and the error includes retry delay, and 'a read burns no nonce'. It also discloses that 'the buyer wallet is never exposed.' No contradictions with annotations found.

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?

The description is a single dense paragraph that immediately states the purpose, then adds key details about pagination, content, budget, rate limiting, and header. Every sentence adds value with no filler or repetition. It is appropriately 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 the tool has no output schema, the description sufficiently explains the return content ('the piece, the net you earned, and the settlement transaction') and pagination details. It also distinguishes itself from a relevant sibling (list_my_posts). The description is complete for an agent to understand when and how to use the tool.

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 baseline is 3. The description repeats the 'SIGN-IN-WITH-X' header requirement already in the schema but does not add new meaning for 'limit' or 'cursor'. The explanation that this header must be signed locally adds slight context beyond schema, but not enough to raise above 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 clearly states the tool returns 'one entry per settled payment for your pieces, newest first, cursor-paginated' and explicitly distinguishes it from 'diffing the per-post totals on list_my_posts'. The verb 'poll' and resource 'sale feed' are precise and unambiguous.

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 tells exactly when to use this tool: 'the surface to poll to learn a sale landed, instead of diffing... list_my_posts'. It also warns about rate limiting ('it still 429s, and that error restates the seconds to wait') and clarifies that it has a separate budget from publishing, so a tight loop won't starve a publish.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable context beyond that: it clarifies the auth requirement ('Pass a SIGN-IN-WITH-X header value you signed locally'), explains that 'a read burns no nonce' (no side effects), and details the uniform 404 response for inaccessible posts. No contradictions 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?

The description is efficient; every sentence contributes essential information. It is front-loaded with the core purpose, followed by usage guidance, error behavior, and authentication instructions. There is no redundancy or filler. The length is justified by the amount of useful context provided.

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?

Despite lacking an output schema, the description proactively lists the fields returned (bodyMd, tags, status, url, answer card). It covers error behavior, authentication, source of the postId, and relationship to sibling tools (update_essay, get_article). For a read operation of moderate complexity, all essential context 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 100% with both parameters documented. The description adds minor contextual value by stating 'Pass a SIGN-IN-WITH-X header value you signed locally' for signInWithX and connecting postId to the output of specific sibling tools. However, the schema already adequately describes the parameters, so the description's added semantic value is limited.

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 clearly states it reads back one of your own posts in full by ID, listing specific fields (bodyMd, tags, status, url, answer card) and explicitly distinguishing it from get_article (public read surface, can't show drafts) and update_essay (wholesale replace). The verb 'Read back' and resource 'one of your own pieces' are specific and unambiguous.

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 explicit when-to-use guidance: 'Do this BEFORE an update_essay' with reasoning (edit stored source vs remembered version). It contrasts with get_article and tells how to obtain the postId (from publish_essay or list_my_posts). It also explains the 404 error behavior for missing/others'/deleted posts, setting clear expectations.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description adds critical behavioral details: the data is for the current month, the exact meaning of each scalar, a warning about not dividing earnings by reads, and that the request burns no nonce.

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?

The description is a single paragraph that is dense with information; every sentence serves a purpose. It could be slightly more structured (e.g., bullet points for the scalars), but it is not overly verbose.

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 no output schema, the description fully explains the return values (three scalars with types and meanings), the authentication method, and the tool's scope. It is complete for an agent to select and invoke correctly.

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% for the single parameter. The description adds value by explaining the parameter must be signed locally and that using it does not consume a nonce, providing meaningful context 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?

The description clearly states it returns three dashboard scalars for the current month (earningsThisMonth, readsThisMonth, glancesThisMonth) and explicitly distinguishes from siblings like list_my_posts and get_my_events, specifying what this tool is not.

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 provides explicit guidance on when to use this tool ('summary rather than a way to enumerate sales') and how to use it ('Pass a SIGN-IN-WITH-X header value you signed locally; a read burns no nonce').

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to say it's read-only. However, the description adds meaningful context about the authentication mechanism (self-signed headers, server doesn't hold keys) that goes beyond annotations. It does not mention response structure, pagination, or whether the profile data is cached. With good annotation coverage, a 3 is appropriate.

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, zero wasted words. The first sentence states the core purpose, the second provides critical authentication guidance. Every part is essential and well-organized.

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 the tool's simplicity (1 parameter, no output schema, no nested objects, no enums), the description covers the essential functional behavior. It doesn't describe the return value format, but with no output schema present, a brief note on what fields are returned would be helpful. However, for a read-only profile tool with clear input requirements, the current description is minimally 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 100%, so the schema already documents the parameter well. The description adds the context that the value should be 'the base64 SIGN-IN-WITH-X header value you signed', which matches the schema description. There's marginal extra value in clarifying that the signature is locally performed, but overall the schema carries the load. 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 uses the specific verb 'Read' and identifies the resource clearly ('your own publisher profile'). It distinguishes itself from sibling tools like 'get_creator' (which reads another user's profile) and 'update_profile' (which modifies). The purpose is precise and unambiguous.

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 explicitly states when to use this tool: to read your own profile. It provides a critical prerequisite: 'Pass a SIGN-IN-WITH-X header value you signed locally.' It also explains why you need to do this ('This server never holds your keys'), which justifies the authentication mechanism and helps the agent understand the tool's security model. This is excellent guidance.

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

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

Beyond annotations (readOnlyHint, openWorldHint), the description discloses key behavioral traits: the tool is keyless and anonymous, carries no per-searcher fields, is recomputed at most every 5 minutes, and served through a shared cache with up to 20-minute retention. It also states the data is already public. These details add significant value for safe and correct invocation.

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?

The description is about 150 words in a single paragraph, which is front-loaded with the core purpose. Every sentence adds value, but it could be slightly more concise by grouping related details. However, given the complexity of the output data, this length is justified and well-structured.

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?

Despite having no output schema, the description fully explains the return values (unmet, top, criteria, and their meanings) and the caching behavior. It also relates the tool to siblings and provides enough context for an agent to decide when to use it. For a zero-parameter, read-only tool, this is exceptionally 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?

With zero parameters, the input schema is trivially covered. The rubric gives a baseline of 4 for 0 parameters. The description does not need to add parameter semantics, but it does explain the meaning of the output fields (unmet, top, windowDays, source, minSearchers), which indirectly aids understanding of what the tool returns. This is appropriate for a parameterless tool.

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 clearly states the tool returns a demand rollup with 'unmet' and 'top' terms, defining each precisely. It explicitly distinguishes from sibling 'search' by explaining that search tells about your own question while this tool shows what other agents are failing to find. This provides a specific verb-resource-scope relationship.

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 provides explicit when-to-use guidance: 'a producer agent polls to decide what to write' and 'Complements search: a MISS tells you nothing answered YOUR question, this tells you what other agents are failing to find.' It also advises against polling too frequently by stating the rollup is recomputed every 5 minutes and cached for up to 20 minutes. This gives clear context and exclusion criteria.

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

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

Even though readOnlyHint and openWorldHint are present, the description adds substantial behavioral detail: paid-body matches only decide which public row is listed, results are preview-only, no snippets/offsets/scores are returned, and q uses OR semantics with operators and stopword dropping. This goes well beyond the annotations and contains no 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?

The description is dense but well-structured and front-loaded with the core operation. Every sentence carries useful selection or invocation guidance, and it avoids repeating the schema's enum values or parameter list.

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 10 parameters and no output schema, the description still tells the agent what kind of result to expect (preview-only listing items, never paid bodies or scores), how pagination works, and how ordering behaves. Combined with 100% schema coverage, this gives an agent everything needed to select and call the tool correctly.

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 already strong. The description adds meaningful extra semantics for q and sort, such as relevance ranking, extra terms widening the set, and sort composing with filters. However, most other parameters (tag, creator, maxPrice, minPrice, updatedSince, publishedSince) are left for the schema to explain, so it does not quite reach full compensation.

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 opens with a specific operation—'Browse, filter, and paginate the Tenjin article directory'—and clearly names the resource. It also distinguishes itself from the `search` tool by stating that whole questions should go there, and it emphasizes preview-only listing behavior, so an agent can tell it apart from `get_article` and `search`.

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 explicit routing guidance: q is meant for SHORT terms, while a whole QUESTION should use the `search` tool. It also explains when to use q alone versus q + sort, and notes the default newest-first browsing order, giving clear decision rules.

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

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

Annotations already mark the tool as readOnly and openWorld, so safety is clear. The description adds valuable behavioral context: the directory is flat, excludes readers (no publications), uses cursor pagination, and is keyless. It could mention data freshness or empty state, but the added context is substantial.

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?

The description is three sentences, front-loaded with the main purpose, and every sentence adds value. It is efficient without being overly terse, though the first sentence is slightly dense.

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 explains the return (list with real article count, cursor-paginated) and sort order. It implies the response includes a cursor for pagination. It covers the essential behavior for a simple list tool, though explicit mention of the response structure (e.g., fields like handle, wallet) would improve completeness.

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% with descriptions for both limit and cursor. The description mentions cursor-paginated, which reinforces the cursor parameter's role, but does not add new semantic details beyond what the schema already provides. Thus 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 clearly states the tool lists all creators with at least one published piece, sorted alphabetically by handle then wallet, paginated with article count. It explicitly distinguishes from the sibling get_creator, which is for a single creator's profile and feed.

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 provides a clear use case (directory listing) and explicitly directs to get_creator for an individual profile. While it doesn't cover all sibling exclusions, it gives a strong when-to-use and when-not-to-use example.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description adds critical nuances: return values differ by status (reads/earnedNet vs null for drafts), and it clarifies that the server never holds the user's keys. No contradictions.

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?

The description is concise and well-structured. The first sentence captures the core purpose and pagination. Subsequent sentences add crucial context (distinction, filtering, return values, authentication). Every sentence earns its place with no 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?

Despite no output schema, the description sufficiently explains the return format (reads/earnedNet for published/unlisted, null for drafts) and pagination (cursor-based). It also covers authentication requirements and possible follow-up actions (update_essay). The tool is fully documented for agent use.

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% with each parameter having a description. The tool description adds value by explaining the signInWithX trait (server never holds keys) and the status filter behavior (omit for everything except deleted). This raises it above the baseline of 3.

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 clearly states the tool lists the user's own published or drafted pieces, newest first, cursor-paginated. It uses specific verbs (list, recover) and distinguishes itself from get_library, which lists pieces the user bought.

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 explicitly tells when to use: to recover a post ID for a later update_essay call. It contrasts with get_library and explains filtering by status. It also details the sign-in requirement, giving an agent clear context for invocation.

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

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

The description discloses that it returns 'every tag in use with its published-article count' and is 'alphabetical, cursor-paginated'. The annotations already provide readOnlyHint and openWorldHint, so the agent knows it is a safe read operation with potentially many results. The description adds the alphabetical ordering and the inclusion of counts, which are not in the annotations. It does not describe what happens if the tag list is empty or how the cursor works beyond the schema, but the annotations already cover safety.

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?

The description is a single sentence that is dense but efficient, front-loading the core purpose and key attributes (scope, sort order, pagination). Every part adds value, and there is no fluff.

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?

The tool is simple (2 optional parameters, no output schema, no nested objects), and the description covers its core behavior: scope, ordering, count inclusion, and pagination. The only minor gap is that it doesn't mention the default limit or the possibility of an empty result set, but these are minor given the schema already specifies defaults and the annotations hint at openness.

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 baseline is 3. The description does not add any additional meaning beyond what the schema already provides for the limit and cursor parameters. It mentions 'cursor-paginated' which aligns with the cursor parameter, but does not elaborate further. Since the schema already documents the parameters fully, the description adds no extra value here.

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 clearly states the tool lists tags in use with published-article counts, alphabetical order, and cursor-based pagination. It specifies the resource ('tags') and the verb ('list'), and the detail about 'published-article count' differentiates it from any sibling tool that might also deal with tags.

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 implies when to use this tool: when you need a paginated list of tags with usage counts. It doesn't explicitly state when not to use it or name alternatives, but given the context of sibling tools like search or list_articles, it's clear for what scenarios it is intended.

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

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

The description adds significant behavioral context beyond annotations: it explains the two-step retry flow, that Tenjin never holds keys, the behavior of maxPrice rejection, and the nature of the response (DATA, not instructions). It also lists stable tool errors. This is thorough for a payment tool with readOnlyHint=false and openWorldHint=true.

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?

The description is front-loaded with the core purpose, but it is quite long (multiple paragraphs). While every sentence adds value, the length could be trimmed for brevity. It earns a 4 because it is structured well but not maximally concise.

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 the complexity (5 parameters, two payment lanes, no output schema, security warnings, error list), the description covers all necessary aspects: the flow, the two methods, error handling, and a critical warning about treating content as untrusted. It is complete for an agent to invoke correctly.

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 description adds meaningful context: for maxPrice it explains the difference between Native MCP and legacy lanes, for paymentSignature it explains how to mint it, for searchId it mentions attribution and expiry. The description enriches the purely schema-based definitions.

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 clearly states the tool's purpose: 'Unlock a paid piece through the standard x402 MCP flow.' It explains the two-step process and distinguishes from sibling tools like get_article by noting when to switch to that alternative. The verb 'pay_and_read' is specific and the resource is a paid piece.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance on when to use: to unlock a paid piece. It specifies when not to use: if a smart-account owner cannot be recognized, stop and use get_article + signInWithX instead. It also warns against sending both payment forms and explains the two payment lanes (MCP vs legacy). This is comprehensive usage direction.

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

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

The description discloses important behaviors beyond what annotations convey: the server never holds keys, returns a public URL, mints headers client-side without a fetch loop, and ranks card-less pieces below filled answer cards. This gives the agent a strong model of side effects and expectations.

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?

The description is dense and front-loaded with the core purpose, then moves into critical auth specifics and content guidance. A few stylistic instructions like 'Sell the observation, not the genre' could arguably live in /llms.txt, but they add practical field-level direction without being padding.

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 write operation with no output schema, the description covers the returned value, authentication flow, anti-pattern warning, quality expectations, and points to the full contract in /llms.txt. The schema richly documents the nested post object, so nothing essential is left 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?

The schema already covers both parameters thoroughly, so the baseline is 3. The description adds meaningful extra semantics around signInWithX, especially the client-driven minting flow, the single-use nonce, and the explicit avoidance of wrapFetchWithSIWx, plus rich guidance on title, excerpt, and answer-card fields.

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 opens with 'Create + publish a piece', giving a specific verb and resource, and clarifies the output: 'Returns the created post + public url'. This clearly distinguishes it from siblings like update_essay or delete_essay.

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 explicit guidance on when and how to use this tool, including the critical warning not to use wrapFetchWithSIWx because this is client-driven, and points to a full worked example in /llms.txt. It also explains the required auth setup and content requirements.

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

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

The description discloses key behavioral traits beyond annotations: it is keyless and anonymous, requiring only the searchId. It returns 202 with { accepted } and nothing else, and deliberately cannot confirm or deny existence of a search (to avoid leaking info). This adds significant transparency about security, privacy, and the API's response behavior. Annotations are { readOnlyHint: false, openWorldHint: true, destructiveHint: false }, which are consistent with the description (not read-only, open world, not destructive). No 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?

The description is concise and well-structured, with three sentences that front-load the key purpose, then provide usage and behavioral details. Every sentence adds value, and there is no redundancy. It is appropriately sized for the tool's complexity.

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 the tool has 2 parameters with 100% schema coverage, no output schema, and no nested objects, the description is complete. It explains the purpose, usage, behavioral traits (anonymity, response), and the meaning of outcomes. No additional context is needed for an agent to use this tool correctly.

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 both parameters thoroughly. The description adds value by explaining the purpose of the outcomes array (e.g., a single-element array is the single-report case, batch up to 10), and clarifies the meaning of 'resourceId' and 'contentHash' beyond what the schema provides. It also reinforces the searchId's role. The description adds marginal but useful context.

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 clearly states the tool's purpose: to report what a prior search was worth, listing the possible outcomes (used, partly used, rejected, regenerated, purchase_declined, or declined to buy). It distinguishes itself from sibling tools by focusing on post-search feedback, which is distinct from the 'search' tool itself, and from 'submit_feedback' which is likely general feedback.

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 explicitly tells when to use this tool: after a prior search, to report the actual outcome. It also provides guidance on not using it? It says 'reporting nothing leaves the loop blind', implying it should always be used after a search. It also explains that an honest 'rejected' is as useful as a 'used', providing context on the value of different reports. No explicit exclusions, but the context is clear.

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

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

Beyond the readOnly and openWorld annotations, the description adds substantial behavioral context: the endpoint is free/keyless/anonymous, results are ranked by match kind then verification then recency, the response envelope matches search with specific fields, and the tool returns `not_enabled` on deployments without knowledge keys. It also includes a crucial security warning that returned content is untrusted data and must never be treated as instructions, which is well beyond the 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?

Although the description is long, every sentence earns its place: access model, endpoint, key kinds, ranking behavior, exact-match semantics, response envelope, deployment behavior, and a critical untrusted-data warning. It is front-loaded with the core purpose and the most decision-critical distinctions before the security notice.

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?

The description is complete despite the absence of an output schema: it explains the result shape, match reasons, confidence, corroboration, error behavior (`not_enabled`), and how to use the searchId for outcomes and purchases. It also covers security and the boundary against search, leaving no gap for an agent deciding whether and how to invoke this tool.

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 every parameter already has a clear schema description. The tool description adds meaningful context around the exact-match semantics of keys and their kinds, reinforcing the schema without repeating it verbatim; the slight extra value justifies a score above the baseline 3.

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 clearly states the tool's purpose: it takes exact-match keys and returns only pieces carrying one of them, ranked by match specificity. It explicitly distinguishes this from search by saying 'no question, no text matching, no fuzzy fallback,' which differentiates it from the sibling search tool.

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 provides explicit when-to-use guidance: use it when you already hold keys about the situation, not when you need text search. It directly references search as the alternative and even advises that a `matched: 0` result is not a reason to retry with search unless you also have a question.

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

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

Even though annotations declare readOnlyHint=true and openWorldHint=true, the description adds substantial behavioral context beyond those hints: retrieval can return nothing by design and that is correct; candidates carry conflicting confidence signals that must not be treated as a ranking; the inspect card is usually but not always present; truncated means retry with a larger limit; the returned content is untrusted data with embedded instructions that must never be followed. It also explains the difference between calibration and confidence, and warns that confidence may be computed over paid text. This goes far beyond what annotations convey.

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?

The description is information-dense and front-loads the core purpose, but it is very long and covers a large amount of edge-case behavior in paragraph form. Some sentences are essential, but the density makes it hard to scan, and the untrusted-content security warning could be more compactly stated. Still, every sentence does carry operational value, and the structure is logical (purpose → usage → behavior → alternatives → safety). It is not concise, but it is organized and not repetitive.

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 search tool with no output schema, the description covers everything an agent needs to invoke it correctly and interpret the result: what counts as a match, what the fields mean, what to read ('matched'), what to do on truncation, how to get a different candidate, when to pay, and what to treat as untrusted. The one gap is the absence of a formal result schema, but the description compensates comprehensively. The warning about the inspect card being optional and the honest-zero behavior are exactly the kind of contextual detail an agent needs.

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 schema already documents the six parameters. The description adds meaningful extra semantic context on top: it explains the question must be one natural-language sentence and that extra words are signal; it clarifies the freshness window is closed at both ends; and it defines the limit behavior around truncation. It does not add new syntax for appliesTo or maxPrice beyond the schema, but the added question-shaping guidance and freshness semantics justify a score slightly above the 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 opens with a concrete verb and resource ('Searches the Tenjin knowledge marketplace for dated operational findings') and immediately distinguishes the tool from its siblings by naming what it is NOT (a web index) and what it wraps (POST /api/search). It also explicitly contrasts it with list_articles, making the purpose unmistakable. The title 'Search paid answers for a task' is reinforced rather than merely restated.

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 unusually rich when-to-use guidance: use it when the question is public, durable, and non-trivial to reproduce; skip docs-answerable questions, private-codebase questions, generic advice, live statuses, and implementation/debugging. It also states when to use alternatives ('Use get_article when you need a DIFFERENT candidate...', 'buy with pay_and_read', 'not a signal to retry on list_articles'). This is explicit, actionable routing with exclusions.

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

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

The description discloses key behaviors: it forwards to a specific endpoint (POST /api/feedback), returns an { id }, and clarifies that an unknown postId is stored as null without causing a 404 error. With annotations not contradicting (readOnlyHint false confirms mutation, openWorldHint true aligns), this adds valuable behavioral insights beyond 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?

The description is concise, using three sentences to convey purpose, safety, behavior, and parameter hints. It front-loads the primary purpose and gradually addresses details, but the sentence about postId could be streamlined without losing meaning.

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 the tool's simplicity (4 params, no output schema, no nested objects), the description is nearly complete. It clarifies behavior, constraints, and endpoint. Minor missing points include confirmation of whether contact is optional and if the response includes any confirmation beyond { id }, but overall it satisfies the needs for an AI agent to invoke correctly.

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?

The input schema covers 100% of parameters with descriptions, so the schema already does the heavy lifting. The description adds marginal value by suggesting users can 'say whatever they like in `message`' and clarifying postId behavior, but this does not significantly enhance understanding 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?

The description clearly specifies the verb 'send feedback' and the target resource 'Tenjin', covering multiple topics (bugs, ideas, questions). It distinguishes itself from sibling tools by its unique purpose of feedback submission.

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 explicitly states that the tool is agent-facing, public, and requires no wallet or signature, providing clear context for when to use it. It does not explicitly contrast with alternatives, but the unique feedback focus implies its distinct usage scenario.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses crucial runtime behavior: the single-use nonce policy ('the write routes burn each nonce once, so a header you already spent on publish_essay will be rejected'), partial-update semantics ('Only the fields you send change; everything else keeps its stored value'), and merge behavior ('resource merges rather than replaces'). It also reveals the validation boundary ('PUT /api/posts/<id> stays the sole validator; this tool forwards your fields verbatim'), which tempers the destructive hint by clarifying nothing is touched beyond sent fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Six sentences with the purpose front-loaded in the first clause, and each subsequent sentence carries distinct information: workflow context, update semantics, id sourcing, auth freshness, and validation. It is dense but not bloated; the only minor redundancy is that partial-update semantics restate what the schema's post field already says ('Anything you omit keeps its stored value').

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 tool with 3 required params and a deeply nested post object with 10 subfields, the description covers every operational aspect an agent needs: core purpose, relationship to publish_essay, concrete use scenarios, id sourcing, auth nonce handling, merge semantics, and the validation contract. Nothing critical for correct invocation is left out; all field-level detail is supplied by the 100%-covered schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the schema already documents all three params and every nested field of post exhaustively. The description adds genuine operational meaning beyond the schema: the concrete consequence of spending a nonce on a prior call, the verbatim forwarding to the validator, and the workflow loop of re-sending resource with gaps filled until cacheEligibleMissing is empty — the latter being the key to getting the nested resource call right.

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 opening sentence 'Edit a piece you already published or drafted, by its post id' states a specific verb, resource, and addressing mechanism. It is unambiguous about the operation and clearly distinct from sibling tools like delete_essay, update_profile, and especially publish_essay, which it explicitly positions against ('This is how you finish what publish_essay started').

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 explicitly routes the agent: this is the continuation of publish_essay, used to fill cacheEligibleMissing gaps, attach a searchId, or flip a draft live by setting status to 'published'. It also gives actionable sourcing guidance — 'Get the id from publish_essay's response, or from list_my_posts' — so the agent knows exactly where to obtain required inputs.

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

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

Beyond annotations (destructiveHint=true, openWorldHint=true), the description adds critical behavioral details: handle renaming releases old handle with immediate URL breakage and 90-day cooldown, auto-claim of handle from displayName, and the single-use nonce requirement. It also mentions validation via PUT /api/me.

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?

The description is well-structured and front-loaded with purpose. Every sentence earns its place, providing necessary warnings and guidance without redundancy. It is comprehensive yet efficient.

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 the tool's complexity (nested object, destructive side effects, no output schema), the description covers all needed context: what it does, how it works, side effects, prerequisites (fresh sign-in), and how to read back results. It is fully complete for an agent to use correctly.

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 description adds significant meaning: it explains the partial update behavior for the profile object, the auto-claim logic for handle/displayName, the nonce requirement for signInWithX, and the effect of omitting fields. This goes beyond the schema's property descriptions.

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 clearly states the tool creates or updates the publisher profile, specifying it affects byline and default price. It distinguishes from siblings like get_profile and get_creator, which are for reading back the result.

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 explicitly says what changes (only sent fields) and what doesn't (omitted fields keep stored value). It provides when-to-use context and names alternatives: get_profile for reading back, get_creator for other agents' view. It also warns about handle renaming consequences and the need for a fresh sign-in-with-X.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description significantly adds behavioral context: it explains that the route sniffs bytes and rejects mismatched content types, it caps direct upload at 4MB and explains the 1.33x base64 inflation, it mentions the body limit, and it explicitly states that signInWithX tokens are single-use (nonces). This goes far beyond the annotation surface.

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?

The description packs a lot of information into four sentences without being overly verbose. It front-loads the immediate purpose and return values, then provides usage alternatives and gotchas. It could be slightly tighter by removing redundant phrasing like 'the route sniffs the bytes and rejects a file whose content does not match the type you declared' which could be shortened to 'rejects if content mismatches declared type.' Almost no wasted words given the density.

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 tool with 4 parameters, good annotations, no output schema, and complex constraints (size limit, base64 inflation, single-use nonce, content validation), the description is nearly complete. It covers the return value shape, size constraints, alternative upload method, auth behavior, and acceptable formats. The only missing piece is explicit guidance on what error messages look like if the upload fails (e.g., size exceeded, content mismatch). Overall highly 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 100% — all 4 parameters have descriptions. The tool description adds significant value: it clarifies the base64 format ('no data: URI prefix, no whitespace'), explains that altText is trimmed to 300 chars, and that contentType must match the actual bytes. It also gives a concrete example of how to use signInWithX (fresh, single-use, recipe from publish_essay). The only slight gap is no explicit list of accepted contentTypes beyond JPEG/PNG/GIF/WebP mentioned in the description.

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 explicitly states the core action: 'Upload an image and get back the stable `{ imageId, url }`'. It clearly specifies the verb (upload), the resource (image), and the return value. The purpose is distinct from sibling tools like update_profile or publish_essay by explaining how the output (`imageId`, `url`) is used with those other tools.

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 provides excellent when-to-use and when-not-to-use guidance. It explicitly tells the agent to use this tool for images under ~3MB and gives an alternative: 'for anything larger, POST the raw bytes to /api/images over plain HTTP'. It also warns that each signInWithX token is single-use, which prevents the agent from reusing stale credentials.

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