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 are provided, so the description bears full responsibility. It discloses all key behaviors: returns an ID for async polling, kapoost answers on his own schedule (minutes to days), do not block, persist ID, rate limit of 5 per hour per IP, and max character limits. No contradictions.

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

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

The description is dense but well-structured: first line defines the action, then critical behavioral notes, usage guidelines, examples, and constraints. Every sentence adds value, though slightly longer than necessary for the 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?

Despite no output schema, the description fully explains the return value (an ID), how to retrieve the answer (poll fetch_answer), and the async nature. It covers rate limits, max lengths, and example questions. It provides sufficient context for correct use.

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

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

Schema coverage is 100%, but the description adds a 500-char max for the 'context' parameter that is not in the schema. It also repeats the 1000-char limit for question. The 'question' parameter is described as plain text in both. Overall, helpful additions 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 action: 'Ask kapoost a question that requires human judgement.' It distinguishes the tool from siblings by mentioning 'poll fetch_answer(id) later' to retrieve the response, showing the unique async pattern.

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 usage guidelines: 'Use sparingly: only when the answer materially affects your task and is not derivable from the content.' Also provides when-not: 'Do NOT block waiting on the answer in this session.' Suggests polling via fetch_answer across sessions and gives cadence advice.

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, but it does not mention error handling, prerequisites, side effects, or rate limits. The behavioral transparency is basic.

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

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

The description is two sentences long, direct, and free of extraneous information. Every sentence adds value, making it concise 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 no output schema, the description partially explains the return value ('full context: team personas with prompts, ready for work'). However, it does not specify the response format or error behavior. For a simple single-parameter tool, this is minimally adequate but not comprehensive.

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 'code' parameter described as 'Session code from the user (a short Polish poetry fragment)'. The description adds no new information beyond rephrasing the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool authenticates with a session code and returns full context including team personas and prompts. It uses a specific verb ('Authenticate') and resource ('session code'), and it distinguishes itself from sibling tools as the only authentication-related tool.

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

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

The description implies when to use this tool (when authentication is needed) by instructing to ask the user for the session code. It does not explicitly state when not to use or mention alternatives, but given no sibling serves a similar purpose, the context is adequate.

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 bears full responsibility. It discloses the authentication method but fails to mention that deletion is irreversible, potential side effects, or permission requirements beyond the token. This is insufficient for a destructive operation.

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 only one sentence and a header requirement. It front-loads the main action and essential authentication detail. However, it could be slightly more structured by separating the action from the auth requirement.

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 simplicity (one parameter, no output schema, no annotations), the description is too minimal. It lacks information on return value, error handling, idempotency, and what constitutes a successful delete. A more complete description would improve agent reliability.

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 single parameter 'slug' is not described beyond the name. The schema has 0% description coverage, and the description only says 'by slug' without defining what a slug is, format expectations, or examples. The agent must infer the meaning, which may lead to errors.

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), the resource (skill), and the identifier (slug). It distinguishes from siblings like get_skill, upsert_skill, and list_skills by specifying the destructive nature and the required parameter.

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 an authentication requirement (agent token) but does not provide guidance on when to use this tool over alternatives, nor does it specify when not to use it. It implies usage for deletion, but lacks explicit context for decision-making.

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 marks the question as fetched on first retrieval, that the answer is asynchronous, and that there is a rate limit (30 polls per hour per IP). This is comprehensive behavioral context.

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 primary purpose, followed by details about asynchronous behavior and usage guidelines. Every sentence adds value, and there is no wasted text.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description covers all necessary aspects: what it does, when to use it, behavioral nuances, and rate limits. It is complete without needing additional fields.

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 only parameter is 'id', which is described in the schema as 'Question ID returned by ask_human.' The description implies this context but doesn't add additional meaning beyond the schema. With 100% schema coverage, this is adequate, though it could explicitly restate the parameter's purpose.

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

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

The description uses a specific verb ('retrieve') and resource ('answer to a previously-submitted ask_human question'), clearly distinguishing it from sibling tools like ask_human (which submits) and submit_answer (which likely submits an answer). The tool's role is unambiguous.

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

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

The description explicitly states when to use the tool (when you need the answer), and more importantly, when not to use it: it advises against tight polling and suggests a reasonable cadence (once per session or every few hours). This prevents misuse and provides context for 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?

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?

With no annotations provided, the description fully discloses the tool's behavior: it returns certificate details (license, price, originality, hash, signature) and provides an example response. There are no contradictions.

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

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

The description is two sentences followed by an example, all front-loaded with key information. Every sentence provides value and there is 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?

Given the tool's simplicity (one parameter, no output schema), the description covers purpose, usage, return contents, and provides an example. It is fully informative for the agent to select and invoke the tool correctly.

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

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

The input schema defines a single parameter 'slug' with a basic description. The description adds an example ('deka-log') and clarifies the return values, which adds meaning beyond the schema. Since schema coverage is 100%, baseline is 3, but the example elevates it.

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

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

The description explicitly states 'Get the full intellectual property certificate for a piece' and lists specific components (license terms, price, originality index, content hash, Ed25519 signature). This clearly defines the tool's purpose and distinguishes it from sibling tools like read_content or verify_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?

The description includes 'Use before quoting or adapting', which gives a clear usage context. It does not explicitly mention when not to use or provide alternatives, but the guidance is sufficient for the agent to decide.

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 bears full burden. Discloses authentication requirement but does not state whether operation is read-only or has side effects. Adequate but not comprehensive.

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 purpose, no redundant words. Highly concise 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?

No output schema exists, yet description does not specify return format or field details. Mentions 'full details' and 'full prompt body' but lacks completeness. Adequate for a simple getter.

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

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

Schema coverage is 100% and the description only reiterates 'by slug', adding no meaningful extra information beyond schema. Baseline score for high 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 it retrieves full details of a persona by slug, distinguishing it from list_personas (which lists all) and other getter tools. Could explicitly differentiate from siblings like get_author_profile.

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 authentication requirement for full prompt body, providing some context. Lacks explicit guidance on when to use versus alternatives or prerequisites beyond authentication.

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 adds the behavioral note about bootstrap_session affecting result completeness, but does not disclose other traits like idempotency or read-only nature. The name suggests read operation but description doesn't confirm.

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

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

Two short, direct sentences with no filler. Every word adds value. Front-loaded with the key action.

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

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

For a single-parameter read tool with full schema coverage and no output schema, the description provides essential information including a prerequisite. Could mention what 'full details' includes, but not necessary for usage.

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 with description 'Skill slug (from list_skills)'. Description repeats 'by slug' but adds no new meaning. Baseline of 3 is appropriate.

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

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

Description clearly states 'Get full details of a skill by slug', which is a specific verb-resource combination. It distinguishes from siblings like list_skills (which lists skills) and delete_skill (which deletes).

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?

Description implies a prerequisite with 'Full body available after bootstrap_session', but does not explicitly state when to use this tool versus alternatives (e.g., list_skills). No exclusion or 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?

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 full burden. It discloses that the tool returns name, role, and tags, and notes that full prompts are only available after bootstrap_session, indicating a limitation. However, it does not explicitly state read-only behavior or any 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 sentences, no unnecessary words. The first states the core function, the second provides important context. Every sentence 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?

Given the tool has no parameters and no output schema, the description covers the essentials: what it lists and what it returns. It also notes a limitation. However, it does not mention ordering, pagination (likely none due to zero params), or how the output is structured beyond fields.

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?

There are zero parameters, and the schema coverage is 100% vacuously. The baseline score is 4 per guidelines, and the description adds no parameter info since none are needed.

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

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

The description uses 'List available expert personas' as a specific verb+resource, and mentions return fields (name, role, tags). This clearly distinguishes it from sibling tools like get_persona (single fetch) or bootstrap_session (different 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?

The description hints at usage context by noting that 'Full prompts available after bootstrap_session,' implying that for full details, bootstrap_session is needed. However, it lacks explicit when-to-use vs alternatives 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?

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?

No annotations are provided, so the description carries the full burden. It states 'Create or update', implying idempotent behavior, but does not disclose side effects, required permissions beyond token, error conditions, or what happens on conflict. Significant gaps for a mutation tool.

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 short and direct, with no unnecessary words. However, it lacks structure: could organize auth requirement separately or add more details without losing brevity.

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 4 required parameters, no output schema, and no annotations, the description is insufficient. It does not explain return values, how to know if creation or update occurred, or any error handling. Incomplete for a mutation 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 only 25% (only 'body' has a description). The description adds no information about the parameters, not even mentioning what slug, title, or category are. It fails to compensate for 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 explicitly states 'Create or update a skill', which is a specific verb and resource. It distinguishes from sibling tools like delete_skill and get_skill.

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 the required authentication header, providing some usage context, but it does not specify when to use this tool versus alternatives (e.g., creating or updating separately). No explicit when-to-use or 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 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.