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?

Annotations already mark this as a write operation (readOnlyHint false), but the description adds meaningful behavioral context: the server never holds keys, the header is client-driven with a single-use nonce, the answer card completeness never affects rank or candidacy, and the tool returns a public URL. This goes well 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 dense and front-loaded with the core purpose, then moves through auth, title/excerpt guidance, answer-card expectations, and a worked-example pointer. Every section serves the call, but the length and interleaving of style guidance with technical instructions make it slightly harder to scan than a cleaner bulleted structure.

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 — a nested post object, an unusual client-driven auth flow, and no output schema — the description is thorough: it specifies the return value, flags the common wrapFetchWithSIWx mistake, describes the nonce requirements, explains the answer-card expectations, and references /llms.txt for the full example and validation contract. Nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds value by reinforcing that signInWithX is locally signed, explaining the client-driven minting flow, and warning against wrapFetchWithSIWx. That extra context on the auth parameter is useful but not a full replacement for 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 opens with 'Create + publish a piece', a specific verb plus resource, and immediately states the return value ('Returns the created post + public url'). This clearly separates it from sibling tools like update_essay or delete_essay by emphasizing creation and publication.

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 preconditions and hard exclusions: it tells the agent to mint the SIWX header client-side, explicitly warns 'do NOT use wrapFetchWithSIWx', explains why (Tenjin never sends a challenge), and points to a full worked example in /llms.txt. This is actionable when-to-do and when-not-to-do 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?

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?

Annotations only declare readOnlyHint and openWorldHint, but the description adds extensive behavioral context: exact-match semantics, ranking order, envelope shape with calibration 'key-v1', matchReasons, confidence, corroborated, free-body presence/omission, paid rows never carrying body, searchId reuse, not_enabled failure mode, and a strong warning that returned content is untrusted data, not instructions. This goes far beyond the annotations and is highly valuable.

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 operation and is dense with useful information, with no outright filler. However, it is one long, run-on paragraph; bullet points or clearer sentence breaks would improve scannability for an agent. It is appropriately sized for the tool's complexity but not optimally 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 envelope, match metadata, confidence and corroboration, free vs paid body behavior, searchId usage, error response not_enabled, and security expectations. Shelf auth errors are covered in the input schema. There is no critical missing context for an agent to invoke 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 input schema already documents keys, limit, shelf, and trigger in detail, including exact comparison, shelf auth errors, and telemetry-only trigger. The description adds behavioral framing around keys and limit but no parameter-specific meaning beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Wraps POST /api/keys/resolve: hand it keys... and get back only the pieces that carry one of them.' It also distinguishes itself from search by explicitly saying there is 'no question, no text matching, no fuzzy fallback,' so an agent can clearly tell resolve_keys apart from its closest sibling.

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

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

The description tells the agent when to use this tool: when you already hold exact keys about the situation. It also gives an explicit when-not and alternative: 'matched: 0... is not a reason to retry with search unless you also have a question to ask,' and names search as the alternative. This is direct, actionable 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?

Annotations declare readOnly and openWorld hints; the description goes well beyond by disclosing the free/keyless/anonymous nature, reranking behavior under VOYAGE_API_KEY, confidence/corroborated semantics, `inspect` omission conditions, free-body `body` omission when budget is tight, `truncated` behavior, and an untrusted-data warning. No contradiction with annotations.

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

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

The description is unusually long, but it is structured into topical paragraphs and front-loads the free call and the core gate (reproduction cost). Some marketing-like elaboration could be trimmed, but most sentences carry operational or security information, so the length is largely justified by 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?

With no output schema, the description must explain return semantics itself, and it does: `matched`, `calibration`, `confidence`, `corroborated`, `inspect`, free `body`, `truncated`, and the ~25kB card bound. It also covers failure/omission cases and how to route to get_article or pay_and_read, leaving no major gap for a correct call.

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 already documents all 8 parameters, so baseline is 3; the description raises it by explaining operational edge cases: `budget_ms` can suppress free bodies and force lexical-only retrieval, `limit` interacts with `truncated`, `freshWithin` excludes future dates, and `question` should be natural language rather than keywords. This gives agents behavioral context the schema alone lacks.

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 identifies a specific verb and resource: searching the Tenjin knowledge marketplace for dated operational findings and matching a question against what catalog pieces say. It explicitly distinguishes itself from list_articles by contrasting question-matching against body/title/excerpt with general browsing, so an agent can tell the tools apart.

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 when-to-use criteria ('public, durable rather than live, non-trivial to reproduce') and explicit skip conditions (docs answered in one line, private codebases, live prices, implementation/review/debugging). It also names alternatives such as list_articles for browsing, get_article for fetching a different/free candidate, and pay_and_read for purchasing, plus a single-retry rule.

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?

Annotations already indicate a destructive write, but the description adds substantial behavioral detail: nonces are single-use and burned by write routes, omitted fields keep stored values, resource merges rather than replaces, explicit null/[]/{} clears fields, scanAck is only valid against unchanged content, and searchId claims accumulate. This goes well beyond the annotations and fully sets 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 information-dense and front-loads the main purpose, but one sentence is grammatically garbled ('Improve the public answer-card context its legacy cacheEligibleMissing field named'), and the trailing endpoint/validator detail is not front-loaded and is lower-value. It could be tightened 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?

For a mutation tool with a nested object schema, no output schema, and fairly sparse annotations, the description covers id sourcing, partial updates, merge semantics, nonce policy, scanAck flow, and clearing behavior. The main remaining gap is that it does not clearly describe what the response will contain beyond the cacheEligible echo.

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?

Input schema coverage is 100%, so the schema already documents each parameter. The description adds useful operational semantics beyond the schema: signInWithX must be fresh because publish_essay spent nonces, status:'published' flips a draft live, and searchId attaches to the search MISS the piece answers. That contextualizes the most behavior-sensitive parameters.

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?

Opens with a specific verb and resource: 'Edit a piece you already published or drafted, by its post id.' It also names concrete update actions (flip a draft live, attach searchId, improve legacy cacheEligibleMissing context), making the tool's scope unmistakable and distinct from get/delete/publish 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?

Gives useful prerequisites—obtain the id from publish_essay or list_my_posts, and mint a fresh SIGN-IN-WITH-X header—so an agent knows how to call it. However, it never explicitly states when to prefer this over publish_essay, delete_essay, or another sibling, nor does it give a when-not-to-use exclusion.

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.