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?

With no annotations, the description fully discloses behavioral traits: 'kapoost answers on his own schedule — could be minutes, hours, or days. Do NOT block waiting... Open to any caller — rate-limited to 5 per hour per IP.' It also mentions max lengths and that the return value contains a concrete procedure.

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 longer but well-structured: purpose first, then procedure, then usage rules, and finally examples. Every sentence adds value. Minor redundancy could be trimmed, but overall it's efficiently organized.

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

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

Given no output schema, the description covers the return value (ID), how to retrieve (fetch_answer), rate limits, max lengths, caller openness, and provides concrete examples. It thoroughly addresses the async polling workflow, making it complete for the tool's complexity.

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

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

Schema coverage is 100% (all parameters described in schema), but the description adds value: it specifies max lengths for question (1000 chars) and context (500 chars), explains the 'from' parameter purpose (agent identity), and provides example usage. This goes beyond the schema's basic documentation.

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

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

The description clearly states the purpose: 'Ask kapoost a question that requires human judgement. Returns an ID — poll fetch_answer(id) later to retrieve the response.' It uses a specific verb ('ask'), names the resource ('kapoost'), and distinguishes itself from sibling tools like fetch_answer.

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

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

Explicit guidance is provided: 'Use sparingly: only when the answer materially affects your task and is not derivable from the content.' It also explains the async nature, not to block, and gives detailed procedure for persisting and polling. It excludes when not to use and mentions alternatives (fetch_answer, scheduling).

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?

No annotations provided, so description carries full burden. Discloses polling behavior, rate limits, and return statuses. Missing details on error handling or expiration, but adequate for core usage.

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 and return structure, followed by essential usage guidance. 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 single parameter, no output schema, and no annotations, description covers purpose, return values, polling, and rate limits adequately for correct tool 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 coverage is 100% and description adds context ('Job id returned by run_narada'). Meets baseline; no additional parameter details 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?

Description clearly states it retrieves job results from run_narada, specifying return values (status, persona voices, recommendations). Distinguishes from sibling tools like run_narada.

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 clear guidance on polling interval (every 5-30 seconds) and rate limit (60/hr/IP). Does not explicitly state when not to use or alternatives, but implied context is 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?

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?

With no annotations provided, the description fully covers behavioral aspects: it is read-only, requires edit token, and explains that journals are append-only and written by /dobranoc on rollback detection. This goes beyond basic purpose to disclose data origin and access restrictions.

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: two sentences plus an embedded example. Every sentence adds value—purpose, access, data source, and use case—without redundancy or filler.

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 read tool with one parameter and no output schema, the description adequately covers what it does, who can use it, and when to use it. It could mention the output format, but the stated purpose (reflections) gives sufficient context.

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 fully described in the schema with examples. The tool description adds a usage example and ties the parameter to the persona's identity, providing meaningful context beyond the schema 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?

The description clearly states the tool returns a persona's personal journal, specifically reflections on past recommendations that were rolled back. This distinguishes it from sibling tools like get_persona or get_author_profile, which serve different purposes.

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 'Owner-only (requires edit token)' and provides a concrete use case for narady where a persona needs to recall past mistakes. While it gives clear context, it does not explicitly contrast with alternatives or exclude scenarios.

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?

No annotations provided, so description must cover behavioral traits. It discloses fire-and-forget nature, kapoost's asynchronous reading, no ETA, and anonymity without contact. Could mention message persistence but overall adequate.

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 efficient paragraph with clear structure: purpose, behavior, usage guidelines, alternative. Every sentence contributes meaning with no redundancy.

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

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

Given 5 params (2 required), no output schema, and sibling tools covering overlapping use cases, the description fully covers what the agent needs to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining why context is required and encouraging contact for reply, going beyond schema 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?

Description states specific action 'leave a plain-text message for kapoost', clearly identifying the verb and resource. It distinguishes from sibling 'ask_human' by noting that tool is preferable for questions requiring a reply.

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 states when to use (fire-and-forget, no ETA), what to include (context, contact), what not to claim (will reply/has been notified), and alternative tool (ask_human for reply-needed questions).

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, the description carries full burden; it accurately describes a read-only listing operation with no side effects, though it does not elaborate on permissions or data freshness.

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 front-load the purpose and usage, with no unnecessary 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 no parameters and no output schema, the description fully explains the tool's function and use case, including examples of group tags.

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?

No parameters exist, so schema coverage is 100%; description adds no param info, but baseline is 4 for zero parameters.

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

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

The description clearly states the tool lists distinct group tags with counts, provides examples of groups (humanmcp, adcp, dev, safety), and distinguishes it from the sibling 'load_skill_group'.

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 advises use before 'load_skill_group' to discover groups, giving clear context for when to use this tool versus 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 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?

No annotations, but description covers key behaviors: concatenates full bodies, requires bootstrap_session for full bodies except certain skills, and empty group handling. Only minor omission is no explicit statement of safety (read-only), but it's implied.

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 adding distinct value: action, usage context, conditions. No wasted words, highly 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?

Covers all necessary aspects for a one-parameter tool: purpose, usage triggers, preconditions, and error handling. No gaps given tool simplicity and no 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?

Schema has 100% coverage for the single parameter 'name', describing it as case-insensitive and suggesting discovery via list_skill_groups. Description adds no additional semantic value beyond 'given group name', 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?

Purpose is very clear: return full bodies of skills by group. Differentiated from list_skill_groups (which lists names) and other siblings. Verb 'load' combined with 'skill group' explicitly states resource and action.

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 states when to use with example phrases, indicates precondition (bootstrap_session) and fallback behavior (empty group hint). Distinguishes from list_skill_groups for discovery.

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?

With no annotations, the description carries the full burden. It explains the server-side pipeline including loading context and journal, calling Sonnet to generate the reflection, and appending to the journal. This discloses the mutation and AI generation behavior. It does not cover error handling or return format, but the core traits are well documented.

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 the key action in the first sentence, followed by pipeline details and usage context. Every sentence adds value, and there is no redundancy. It could be slightly more streamlined, but overall it's 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 (3 required params, no output schema), the description adequately covers purpose, internal process, constraints, and usage scenario. It does not explain the return value explicitly, but the output is likely implicit (success/error). The description is complete enough for an AI agent to understand when and how to use it.

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 schema descriptions are already informative. The description adds a constraint for persona_slug ('must be one of the personas that voted on that narada') which is not in the schema. However, overall the description adds limited value beyond what the schema provides, warranting a baseline 3.

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

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

The description clearly states the verb ('ask a persona to reflect' and 'append') and the resource ('its journal'). It distinguishes from siblings by specifying it is for reflecting on past recommendations that turned out wrong, which is unique among the listed tools.

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

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

The description explicitly states it is used by /dobranoc after detecting a rollback of a commit tagged [narada:<id>], providing clear context. It also mentions 'Owner-only' indicating access restriction. However, no exclusions 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?

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?

No annotations provided, so description must carry full burden. It discloses logging ('Logs usage intent') and mentions returning permissions/terms. Lacks details on idempotency, error behavior, or auth requirements, but caller_id parameter implies audit trail.

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 plus a clear example. No redundancy, every part adds value. Front-loaded with the core 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?

No output schema, so description should explain return value – does so briefly ('returns permissions and terms'). Could detail format or error cases, but sufficient for a simple tool with three required params.

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 67% (2 of 3 params have descriptions). Description adds value with an example showing parameter usage and reinforces the purpose of caller_id for audit trail. Compensates for uncovered slug field by implying its role via example.

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 the action ('Declare intended use', 'get license terms') and the resource ('a piece'), with specific context ('Required before commercial use'). Distinguishes from siblings like 'request_access' by focusing on license terms.

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 states when to use ('Required before commercial use') and provides an example. However, no explicit guidance on when not to use or alternatives, though sibling context suggests it's unique among listed 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 asynchronous nature, job ID returned immediately, typical latency (seconds to minute), server-side pipeline picks personas via keyword routing. No annotations provided, but description fully covers behavioral traits.

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 paragraph, front-loaded with core function, includes all necessary info without fluff. 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?

Completeness despite no output schema: explains async pattern, how to retrieve results (fetch_narada_result), usage tips, and context requirements. Adequate for tool complexity.

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 description adds meaning: context should describe situation with example and constraints, from is optional caller identity. Provides value 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?

The description clearly states the tool starts a narada (multi-persona advisory) on given context, returns a job ID, and explains the pipeline. It distinguishes from the sibling fetch_narada_result for retrieving results.

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

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

Explicit guidance: when to use (decisions needing multiple perspectives), what context to provide (situation not just topic), async behavior, typical latency, and explicit sibling for result retrieval.

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?

Discloses deterministic nature, no LLM, and return details (groups, slugs capped at 8, explanations). Without annotations, this adequately describes 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?

Three concise sentences front-load the core purpose and usage, with no redundancy.

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

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

Complete description covering purpose, usage, behavior, and return values despite no output schema. No missing context.

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 all params (100%). Description adds context with examples and purpose for each param, exceeding 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?

Clearly states it maps repo manifest to suggested skill set via deterministic signal matching, distinguishing from sibling tools like list_skills or upsert_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?

Explicitly says 'Use when scaffolding a new project workspace', providing a clear context. Lacks explicit when-not-to-use or alternatives, but sufficient for guidance.

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

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

No annotations provided, so the description carries the full burden. It discloses that it's a destructive write (overwrites patterns), is owner-only, and is used internally for recap. Missing details about rate limits or idempotency, but sufficient for safe invocation.

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

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

The description is concise and well-structured: first sentence states the core action, then explains implications and background. Every sentence adds value, 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?

Given the single parameter and no output schema, the description covers all needed context: what it does, when to use it, authorization, automatic triggers, and internal purpose. No gaps.

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 well-documented in the schema. The description adds no extra semantics beyond repeating the purpose. Schema coverage is 100%, 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 explicitly states the action (synthesise), the resource (persona's journal), and the outcome (set of 3-5 patterns). It clearly distinguishes itself from siblings like get_persona or record_persona_reflection by focusing on pattern synthesis.

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 explains when to force a synthesis (after a spike of reflections) and notes that it happens automatically every ~6h. It also adds owner-only restriction. However, it doesn't explicitly state when NOT to use it, though the automatic schedule implies manual use is exceptional.

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.