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 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?

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?

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?

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?

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?

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.