humanMCP — kapoost

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

No annotations are provided, so the description carries the full burden. It discloses that the tool is safe (no side effects) and lists the returned information types (author, role, endpoint, etc.). This is sufficient for a read-only info tool, though it could mention idempotency.

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 with no waste. The first sentence states the purpose and return types; the second provides usage guidance. Front-loaded and 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?

With no output schema, the description compensates by listing the types of information returned (author, role, MCP endpoint, public web pages, short orientation). This is complete enough for an agent to understand what to expect. Could be improved by noting the format (e.g., plain text or JSON), but adequate.

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 has zero parameters and schema coverage is 100%, so the description need not add parameter details. It appropriately states the tool requires no inputs, achieving a baseline of 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 clearly states the tool's purpose: 'Self-description of this humanMCP server. Returns author, role, MCP endpoint, public web pages, and a short orientation.' It uses specific verbs ('Returns') and resources, and is distinct from sibling tools like 'get_author_profile' or 'get_persona' which serve different functions.

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 'Safe to call without bootstrap_session — meant for first-contact discovery,' providing clear guidance on when to use it (first-contact) and that it requires no prerequisites. While it doesn't explicitly state when not to use it, the context implies it's for initial orientation.

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?

No annotations provided, so description covers all behavioral traits: returns an ID for polling, rate limits, max lengths, open to any caller. Fully transparent about the async nature and constraints.

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?

Very concise yet comprehensive. Front-loaded with purpose, then usage rules, then examples, then constraints. Every sentence adds 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?

Given the human-in-the-loop complexity, description covers purpose, when to use, what returns (ID), how to get response (poll fetch_answer), rate limits, char limits, examples. No output schema but description makes the return value clear.

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% (all parameters described in schema). Description adds value by explaining the polling flow, rate limits, and usage constraints beyond the schema's parameter descriptions. Gains 1 point for additional 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?

Description clearly states 'Ask kapoost a question that requires human judgement' and distinguishes from sibling tool fetch_answer. It specifies the action and the resource (human judgment).

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?

Explicitly says 'Use sparingly: only when the answer materially affects your task and is not derivable from the content.' Includes examples, rate limits (5 per hour per IP), and character limits. Provides clear when-to-use 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool authenticates and returns context, which implies it's a read operation with no destructive effects. However, it doesn't mention potential behavioral traits like rate limits, error handling, or what happens if authentication fails. The description adds basic context but lacks depth for a tool that likely involves sensitive authentication.

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 front-loaded, with two sentences that efficiently convey the tool's purpose and usage. Every sentence adds value: the first states what the tool does, and the second provides actionable guidance. It could be slightly more structured by explicitly listing outputs, but overall it's well-sized with minimal waste.

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 (authentication tool with 2 parameters, no annotations, no output schema), the description is moderately complete. It covers the core purpose and usage but lacks details on outputs (e.g., what 'full context' includes), error cases, or integration with sibling tools. Without an output schema, the description should ideally explain return values more, but it does enough for basic understanding.

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 ('code' and 'format') thoroughly. The description mentions the 'code' parameter implicitly ('session code') but doesn't add any semantic details beyond what the schema provides, such as explaining the 'format' options or their implications. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Authenticate with a session code and receive full context: team personas, skills, and a ready-made system prompt.' It specifies the verb (authenticate) and resource (session code), and mentions the outcome (receive context). However, it doesn't explicitly differentiate this from sibling tools like 'request_access' or 'get_author_profile', which might also involve authentication or context retrieval, so it doesn't reach a 5.

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

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

The description provides explicit usage guidance: 'Ask the user for the session code shown in their humanMCP dashboard. Provide the code to receive your briefing.' This clearly indicates when to use the tool (to authenticate and get context) and includes a prerequisite (obtaining the code from the user). It effectively distinguishes this from other tools by focusing on initial session setup.

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?

With no annotations provided, the description carries full burden. It discloses the authentication requirement ('Requires agent token') but doesn't mention whether deletion is permanent/reversible, what happens to associated data, error conditions, or rate limits. For a destructive operation, this leaves significant behavioral gaps.

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 extremely concise (two short phrases) with zero wasted words. It's front-loaded with the core action and includes a critical prerequisite. Every element earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive tool with no annotations, 0% schema coverage, and no output schema, the description is inadequate. It lacks information about what 'delete' entails, error responses, confirmation requirements, or what the tool returns. The authentication note is helpful but insufficient.

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

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

Schema description coverage is 0%, so the description must compensate. It only states 'by slug' without explaining what a slug is, its format, or where to find it. The single parameter 'slug' remains semantically unclear beyond being an identifier.

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 action ('Delete') and resource ('a skill by slug'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'delete_persona' or 'upsert_skill' beyond mentioning 'skill' specifically.

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 mentions 'Requires agent token' as a prerequisite, but provides no guidance on when to use this tool versus alternatives like 'list_skills' for checking existence or 'upsert_skill' for updates. No explicit when/when-not scenarios are given.

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?

Discloses important side effect: marks question as fetched on first successful retrieval. Also mentions rate limiting. No annotations provided, so description carries burden well.

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

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

Three concise sentences, front-loaded with main purpose, no wasted words.

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?

Complete for a simple tool: explains return values, side effect, rate limiting, and parameter purpose. No output schema but description covers return format.

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 baseline 3. Description adds context that 'id' is question ID from ask_human, but adds no syntax or format details beyond 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?

Description clearly states it retrieves answer to a previously-submitted ask_human question, specifies return format (answer text or 'still awaiting'), and distinguishes from sibling tool ask_human.

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?

Explains when to use (after ask_human), mentions rate limiting (30 polls/hour/IP), and states it's open to any caller. No explicit exclusions, but 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?

Lacks disclosure of side effects, caching, or rate limits, but describes profile content (roles) since no output schema exists.

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, front-loaded with action, every clause adds value (purpose, subject identity, usage timing).

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?

Adequate without output schema; identifies specific subject (kapoost) and implied profile contents, though could hint at data structure.

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?

Baseline score for zero-parameter tool; no parameters to describe.

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?

Specific verb ('Returns') + resource ('full profile of kapoost'), and clearly distinguishes from content-oriented siblings by targeting the specific author identity.

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 sequencing ('Call this first') and rationale ('understand who you are talking to'), though lacks explicit 'when-not' 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?

Discloses critical behavioral traits absent from annotations: temporary nature of OTS stub (base64), ~1hr wait requirement, and mandatory upgrade_timestamp follow-up step.

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

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

Three tightly constructed sentences: action/return values first, critical behavioral caveat second, usage context third; 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?

Compensates for missing output schema by enumerating all returned fields (license, originality index, hash, signature, proof) and explaining the Bitcoin anchoring workflow; sufficient for invocation decision-making.

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% ('Piece slug'), establishing baseline 3; description references 'a piece' but adds no further parameter constraints, format details, or semantic context beyond 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?

Specific verb ('Get') + resource ('intellectual property certificate') with clear differentiation from siblings via detailed return value list and explicit mention of upgrade_timestamp workflow.

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 'Use before quoting or adapting' provides clear when-to-use guidance, though lacks explicit comparison to alternatives like verify_content or request_license.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves a 'full system prompt,' implying a read-only operation, but does not address permissions, error handling, rate limits, or response format. For a tool with zero annotation coverage, this leaves significant behavioral gaps.

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 front-loaded: the first sentence states the core purpose, and the second adds usage context. Both sentences earn their place without redundancy, making it efficient 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?

Given the tool's complexity (retrieving system prompts), lack of annotations, no output schema, and low schema description coverage, the description is incomplete. It does not explain what a 'full system prompt' entails, how errors are handled, or any behavioral traits, leaving the agent with insufficient context for reliable 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?

The input schema has one parameter ('slug') with 0% description coverage, meaning the schema provides no semantic details. The description adds meaning by explaining that 'slug' identifies a persona to retrieve its system prompt, but it does not specify format, examples, or constraints. This partially compensates but is minimal given the low schema coverage.

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: 'Get the full system prompt for a persona by slug.' It specifies the verb ('Get'), resource ('full system prompt for a persona'), and key identifier ('by slug'). However, it does not explicitly differentiate from sibling tools like 'list_personas' or 'get_author_profile,' which slightly limits clarity.

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 includes a usage hint: 'Adopt this persona to assist the author in their preferred style,' which implies when to use it—for adopting a persona's style. However, it lacks explicit guidance on when to choose this tool over alternatives (e.g., 'list_personas' for listing personas or 'upsert_persona' for creating/updating). No exclusions or prerequisites are mentioned.

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?

With no annotations provided, the description carries full burden but only states it's a read operation ('Get') without disclosing behavioral traits like authentication needs, rate limits, error handling, or what 'full body' includes (e.g., structured data vs. raw text). It adds minimal context beyond the basic action, leaving gaps in understanding how the tool behaves.

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 brief and front-loaded with the core purpose in the first sentence. The second sentence ('Read this before starting work with the author.') is somewhat vague but not overly verbose. Overall, it's efficient with minimal waste, though the second sentence could be more informative.

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 low complexity (single parameter, no output schema, no annotations), the description is minimally adequate but lacks details on output format, error cases, or integration with siblings. It states the purpose but doesn't fully cover behavioral aspects or usage context, leaving the agent to infer from the schema alone.

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 description coverage is 100%, with the parameter 'slug' fully documented in the schema. The description adds no additional semantic details beyond implying it's used to identify a specific skill, but with only one parameter, the baseline is high. It doesn't compensate for gaps, but none exist due to full coverage.

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 'Get the full body of a specific skill by slug' which clearly identifies the verb ('Get') and resource ('skill'), but it's somewhat vague about what 'full body' entails (e.g., metadata, content, or both). It doesn't explicitly differentiate from siblings like 'list_skills' or 'get_author_profile', though the specificity of 'by slug' helps somewhat.

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 includes 'Read this before starting work with the author,' which implies a prerequisite or context but is ambiguous and doesn't specify when to use this tool versus alternatives like 'list_skills' for browsing or 'get_author_profile' for author details. No explicit guidance on when-not-to-use or clear alternatives is provided.

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?

Annotation Contradiction: Description states 'Max 2000 chars' while input schema explicitly limits 'text' to 'max 280 chars', creating fatal ambiguity about constraints.

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

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

Front-loaded with purpose, followed by usage rule, example, and side effect; efficient structure though the contradictory length limit at the end creates noise.

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?

Covers essential behavioral side effect ('logs to author dashboard') and workflow trigger; sufficient for a simple write operation without output 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?

Rich concrete example (slug: 'deka-log', text: 'mathematics as poetry') adds usage context beyond 100% schema coverage; clarifies 'from' field semantics as reader identifier.

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?

Explicit verb 'Leave' and resource 'reaction on a specific piece' clearly distinguishes from sibling 'leave_message' (implied to be for direct messages).

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 instruction 'ALWAYS call this after reading' defines trigger condition, plus guidance 'Even one word counts' clarifies content 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?

Adds URL handling note beyond schema, but lacks side-effect disclosure (persistence, notification, privacy) given no 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?

Extremely concise, front-loaded with action, no wasted words.

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?

Adequate for simple tool but omits outcome/result explanation and relationship to 'regarding' parameter.

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 baseline is 3; description adds minimal semantic color beyond schema (only 'URLs are welcome').

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?

Clear verb ('Leave') and resource ('message for kapoost'), but does not explicitly differentiate from sibling 'leave_comment'.

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?

No guidance on when to use vs alternatives (e.g., 'leave_comment') or when-not-to-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?

Discloses return value contents ('type, access level, schema hints, and audience') which is crucial given no output schema or annotations exist.

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, front-loaded with specific nouns, no filler; every clause provides unique information about capabilities or outputs.

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?

Compensates well for missing output schema by documenting return fields; omits optional nature of filters but this is clear from schema structure.

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 has 100% description coverage; description mentions artifact types matching blob_type enum but adds no further parameter context, meeting 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?

Specific verb ('List') and resource ('typed data artifacts') with concrete examples, though it doesn't explicitly distinguish from sibling 'list_content'.

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?

Provides explicit usage context ('Use this to discover...') but lacks 'when not to use' guidance or comparison to alternatives like list_content or read_blob.

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 anonymous callers see only public items, bootstrapped callers may see members, and that IP belongs to creators. This adds significant behavioral context beyond annotations (which are absent).

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 (4 sentences), front-loaded with the main purpose, and contains no superfluous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and no output schema, the description covers purpose, access levels, and attribute list. It could mention pagination or ordering but is adequate for a simple list 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?

The tool has no parameters, so the description does not need to explain them. Schema coverage is trivial at 100%.

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 items in kapoost's personal art collection that he owns but did not create, distinguishing it from list_content which lists his own creations.

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 context for when to use the tool (reading provenance dossiers) and distinguishes it from list_content, but does not explicitly state when not to use it or mention alternative tools.

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?

Discloses returned data structure (slug, title, type, etc.) compensating for missing output schema, but lacks info on pagination, errors, or rate limits.

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

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

Front-loaded and dense; efficiently packs purpose, return values, and filter options into brief text without 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?

Adequately compensates for lack of output schema by enumerating return fields; sufficient for a simple list operation with optional filters.

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 100% schema coverage, baseline is 3; description redundantly confirms filtering behavior already clear in parameter 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?

Clearly states it lists published pieces by 'kapoost' and specifies returned fields, though it doesn't explicitly contrast with sibling 'read_content'.

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?

Mentions filtering capability but provides no guidance on when to use this versus 'read_content' or other content access tools.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool lists personas but doesn't describe the return format (e.g., array of objects with IDs/names), pagination, sorting, error conditions, or whether it requires authentication. For a read operation with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.

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, efficient sentence that directly states the tool's purpose without redundancy. It's front-loaded with the core action ('List available expert personas') and adds clarifying context ('the agent can adopt to assist the author'). There's no wasted verbiage.

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 lack of annotations and output schema, the description is incomplete. It doesn't explain what the output looks like (e.g., structure, fields), potential errors, or dependencies. For a tool that likely returns a list of personas, more detail on the response format would help the agent use it effectively.

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 tool has 0 parameters, and schema description coverage is 100% (though empty). The description doesn't need to explain parameters, so it meets the baseline of 4. It correctly implies no inputs are required, aligning with 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 the tool's purpose: 'List available expert personas the agent can adopt to assist the author.' It specifies the verb ('list') and resource ('expert personas'), and distinguishes it from siblings like 'get_persona' (which likely retrieves a single persona) and 'upsert_persona' (which modifies personas). However, it doesn't explicitly contrast with 'list_skills' or other list tools, keeping it from a perfect score.

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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an active session), exclusions (e.g., not for filtering or searching), or comparisons to siblings like 'list_skills' or 'get_persona'. The agent must infer usage from the name and context alone.

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?

No annotations, but description adds value by stating it is a list operation (no mutation), returns specific fields, and is publicly accessible. No contradictions, but could mention potential rate limits.

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

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

Three sentences, each with clear purpose: defines action, lists return fields, gives usage context. No redundancy, front-loaded with core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but description compensates by listing return fields. One parameter fully documented. Usage context provided. Complete for a simple list 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 baseline 3. Description does not add additional meaning beyond what the schema already provides for the 'slug' parameter.

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 'List the provenance dossier... for an artwork piece' with a specific verb and resource. It returns specific fields, but does not explicitly differentiate from sibling 'read_provenance', which may have a similar purpose.

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?

Explicitly says 'Use to check the chain of custody before quoting authenticity' and 'Open to any caller', providing clear context. However, no when-not-to-use or alternatives are mentioned.

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?

With no annotations provided, the description carries full burden but only states it's a listing operation with filtering. It doesn't disclose behavioral traits like whether this requires authentication, rate limits, pagination behavior, response format, or what happens when no skills match. For a tool with no annotation coverage, this is inadequate.

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 concise sentences with zero waste. First sentence states purpose, second adds filtering capability with helpful examples. Perfectly front-loaded and appropriately sized for a simple listing tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and a simple single-parameter tool, the description is incomplete. It doesn't explain what 'author's skills' means in this context, what format the skills are returned in, or how to interpret the 'instructions for how to work with them' aspect. The description should provide more context about the data model and response expectations.

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

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

Schema description coverage is 100%, so the schema already documents the single parameter 'category' with its description. The description adds marginal value by providing examples of categories ('tech, writing, workflow'), but doesn't explain category semantics beyond what the schema provides. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the verb 'List' and resource 'author's skills' with the purpose 'instructions for how to work with them'. It distinguishes from siblings like get_skill (singular retrieval) and list_content/personas (different resources). However, it doesn't explicitly differentiate from all list_* tools beyond the resource type.

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 context by mentioning filtering by category, but doesn't provide explicit guidance on when to use this tool versus alternatives like get_author_profile (which might include skills) or query_vault (which could search skills). No when-not-to-use guidance or prerequisites are stated.

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?

Excellent disclosure of return format variations (base64 for vectors/images, JSON for datasets) compensating for missing output schema and 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?

Three tight sentences: purpose first, then format details, then parsing instruction. 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?

Comprehensively covers return behavior given lack of output schema, though could note error conditions or accessibility constraints.

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 has 100% coverage; description adds no parameter-specific semantics, meeting baseline expectation.

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

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

States specific action (read) and resource (typed data artifact by slug), distinguishing from list_blobs, though doesn't explicitly contrast with read_content 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?

Provides post-call parsing guidance ('check schema and mime_type'), but lacks explicit when-to-use criteria vs alternatives like read_content.

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?

With no annotations, the description carries full burden. It discloses access control (returns 'not found' for private items unless bootstrapped) and hints at return content (metadata and dossier count). However, it does not explicitly state idempotency or safety, though the tool name implies read-only.

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 with no redundancy: first sentence states purpose and output composition, second adds access control and alternative tool. Front-loaded and every sentence adds 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 simple single-parameter read tool without output schema, the description covers functionality, return composition, access control, and alternative usage. It lacks explicit output format details, but the return values are described enough for agent decision-making.

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 a clear description of the slug parameter. The description reinforces that the slug identifies the item and adds behavioral context about private items, but does not provide additional parameter semantics 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 the tool reads a single collection item by slug, and specifies it returns full metadata and dossier count. It distinguishes from sibling tools like list_collection and read_provenance by its singular focus and by referencing list_provenance as an alternative for the dossier itself.

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

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

The description explicitly directs agents to use list_provenance for fetching the dossier, providing a clear alternative. It does not explicitly state when not to use this tool, but the context of 'read' vs 'list' and the sibling reference are sufficient.

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?

No annotations provided, but description effectively carries the burden by disclosing access control behavior and attribution requirements ('attribute to kapoost').

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

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

Three tightly written sentences: purpose first, behavioral constraints second, usage policy third. 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?

Despite no output schema, description compensates by explaining both return cases (content vs instructions) and includes attribution policy.

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 baseline is 3; description mentions 'by slug' but does not add semantic context beyond the schema's definition.

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?

Clear verb-resource pair ('Read the full text of a piece') and distinguishes from siblings via public/locked behavior differentiation.

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

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

Explains the dual behavior (public content returned immediately vs locked pieces returning access instructions), implicitly guiding the workflow without explicitly naming 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?

No annotations provided; description indicates read operation and file URLs, but does not disclose potential side effects, authentication needs, or rate limits.

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?

Single sentence, efficiently conveys purpose and key differentiator with no superfluous words.

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?

Covers functionality and relationship to sibling tool; lacks detail on file URL behavior or prerequisites, but adequate for a simple read 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 coverage is 100% with adequate descriptions for both parameters; description adds no further parameter semantic value 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?

Clearly states it reads a single provenance item by id, includes file URLs, and distinguishes from list_provenance by specifying the additional return data.

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?

Implies when to use (for a single item with URLs) vs list_provenance, but lacks explicit exclusions or alternative use cases.

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?

With no annotations provided, the description carries full burden for behavioral disclosure. It explains that results are ordered newest first, that the query parameter performs case-insensitive substring matching over body and tags, and that a bootstrap session is required. These details go beyond a simple 'retrieve' verb, but it does not cover all potential traits (e.g., idempotency, error handling).

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 exceptionally concise: four sentences, each serving a distinct purpose (retrieval, ordering, query behavior, usage prerequisite). No redundant phrases, and the most critical information (primary action) is front-loaded. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple retrieval tool with three parameters and no output schema, the description covers the essential aspects: what it retrieves, in what order, filtering options, and when to use it. It does not describe the return format or fields (e.g., body, tags, timestamp), but that is partially mitigated by the absence of an output schema. Overall, it provides sufficient context for correct invocation.

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

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

Schema coverage is 100%, but the description adds meaningful detail beyond the schema: it explains that 'query' filters over body and tags (schema only says 'substring filter'), and that results are newest first (not in schema). However, it does not add extra context for 'code' or 'limit' parameters beyond what the schema provides.

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

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

The description clearly states it retrieves memories by session code, with an explicit verb and resource. It specifies return ordering and optional search, but does not explicitly distinguish from sibling tools like 'remember', which is the complementary write operation. The purpose is clear but sibling differentiation could be stronger.

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

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

The description gives a concrete usage scenario (start of a new session to pick up where left off) and a prerequisite (requires active bootstrap_session). It lacks explicit when-not-to-use alternatives, but the guidance is helpful and context-aware.

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?

No annotations; description mentions text limit and session requirement but does not disclose behavior like overwriting, appending, or limits on memory count.

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 covering purpose, constraints, use cases, and prerequisite. No wasted words.

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 4 params with full schema and no output schema, description provides adequate context. Lacks return value info but acceptable.

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 covers 100% of parameters with descriptions. Description adds minimal beyond schema (e.g., context of 'code' for future recall). Baseline 3 applies.

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

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

Description clearly states it stores a memory under a session code for future recall, with constraints (plain text, 8KB). Distinguished from sibling 'recall' which retrieves.

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?

Explicitly lists use cases (observations, preferences, context) and prerequisite (active bootstrap_session). Lacks when-not-to-use but sufficient.

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?

Discloses dual outcomes (challenge vs payment) and crucial behavioral context that challenges are intentional/part of the work, but omits rate limits or side effects.

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

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

Two dense sentences with no filler; front-loaded with action and return types, second sentence adds essential behavioral clarification.

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?

Well covers return values (challenge/payment info) despite missing output schema and links to sibling workflow, though could hint at payment resolution path.

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 has 100% coverage; description contextualizes 'slug' as referring to a 'locked piece' but adds minimal semantic depth beyond the schema itself.

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?

Specific action (get gate details), clear resource (locked piece), and distinguishes from sibling submit_answer by specifying this retrieves while that submits answers.

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?

Explicitly mentions workflow (answer with submit_answer) and clarifies the challenge is intentional content, though lacks explicit 'when not to use' 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?

Discloses side effect ('Logs usage intent') and return value nature ('returns permissions and terms') without annotations to rely on.

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?

Efficiently packs purpose, constraint, example, and return info into one sentence; front-loaded with action verbs.

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?

Adequate for simple 3-parameter tool; compensates for missing output schema by specifying return values (permissions/terms).

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?

Concrete example clarifies slug format ('deka-log') and intended_use values ('quote in essay'), compensating for missing slug description in 67% schema coverage.

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?

Clearly states core action (declare intent, get license terms) and distinguishes from 'request_access' sibling by emphasizing licensing/commercial use requirements.

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?

Explicitly notes 'Required before commercial use' establishing clear prerequisite context, though lacks explicit 'when not to use' 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?

With no annotations, description carries full burden and discloses key traits: case-insensitivity, success returns full content, and failure handling strategy.

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?

Five sentences, front-loaded with purpose; every sentence adds distinct value (behavior, success case, failure case, design philosophy) without 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?

Adequately compensates for missing output schema by describing return behavior ('full content is returned'); sufficient for simple 2-parameter 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?

Adds 'Case-insensitive' constraint (applies to answer parameter) beyond 100% schema coverage; contextualizes parameters as part of 'challenge gate' workflow.

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?

Specific verb ('Submit') + resource ('answer to a challenge gate') clearly distinguishes from siblings like read_content or leave_comment.

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?

Implies usage context (challenge gates) and provides clear guidance on handling wrong answers ('try a different interpretation'), though lacks explicit when-not-to-use 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the authorization requirement ('Requires agent token'), which is useful context. However, it doesn't describe the upsert logic (e.g., how it determines create vs. update), potential side effects, error handling, or response format. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.

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

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

The description is concise with two sentences that are front-loaded: the first states the purpose, and the second adds an authorization requirement. There's no wasted text, and it's appropriately sized for a simple tool. However, it could be more structured by separating usage notes from core functionality.

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 (a mutation tool with 5 parameters), lack of annotations, no output schema, and low schema coverage, the description is incomplete. It covers the basic purpose and auth need but misses details on behavior, parameters, error cases, and output. For a tool that creates or updates data, this leaves the agent with insufficient context to use it effectively.

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 low (20%), with only 'body' having a description ('Markdown instructions'). The tool description adds no parameter information beyond what's in the schema. It doesn't explain the meaning of 'slug', 'category', 'title', or 'tags', or provide examples or constraints. With 5 parameters and poor schema coverage, the description fails to compensate adequately.

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 verb ('Create or update') and resource ('a skill'), making the purpose unambiguous. It distinguishes from siblings like 'delete_skill' and 'get_skill' by indicating mutation. However, it doesn't specify what a 'skill' is in this context or differentiate from 'upsert_persona' beyond the resource name.

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 no guidance on when to use this tool versus alternatives like 'create_skill' or 'update_skill' (which don't exist in siblings, but the upsert behavior isn't contrasted). It mentions an authorization requirement but doesn't explain prerequisites, error conditions, or typical use cases. No explicit when/when-not instructions are given.

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?

Discloses return values (status + fingerprint) and specific key ownership (kapoost's private key), compensating for missing annotations; omits error handling details.

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 with zero redundancy: purpose first, then usage and return values; every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Fully compensates for missing output schema by detailing return values; adequately covers single-parameter input requirements and behavioral expectations.

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

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

Meets baseline since schema has 100% description coverage; description adds no supplemental parameter context beyond the schema's definition of 'slug'.

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?

Explicitly states the cryptographic verification action (verify authentic signing) and target resource (piece), clearly distinguishing from sibling tools like read_content or list_content.

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?

Provides specific usage context ('before sharing it') but lacks explicit alternatives or exclusions (e.g., doesn't mention when to use read_content instead).

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