humanMCP — kapoost

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses two non-obvious traits: determinism and no bootstrap requirement. This is valuable for an agent deciding whether to invoke the tool. It does not specify return format or side effects, but for a simple metadata probe these omissions are minor.

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

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

The description is a single, well-structured sentence that packs the tool's purpose, key behavioral traits, and usage guidance without any fluff or redundancy. Every word contributes to the agent's understanding.

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 zero-parameter metadata endpoint with no output schema, the description provides sufficient context: it explains what the tool is, when to call it, and what decision it supports. It doesn't explicitly list the contents of the self-description, but the relevance-check framing gives a strong hint. Slightly more detail about return content would make it fully complete.

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

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

The tool accepts zero parameters, so the description has no parameter details to add. Per the rubric, zero-parameter tools receive a baseline score of 4. The description adds no parameter semantics because none exist, which 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 identifies this tool as a self-description of the humanMCP server, with a specific purpose: helping the caller decide whether the rest of the API is relevant. This distinguishes it from sibling tools, which are all functional endpoints, by positioning it as a discovery/metadata entry point.

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 instructs to 'call this first' and notes that no bootstrap is required, giving clear guidance on when to use it. It implies that alternatives are all other API methods, and the relevance-check purpose provides context for its role in the toolset, though it doesn't name specific 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, the description carries the full burden and does an excellent job: it discloses the async behavior (returns ID, not an immediate answer), the rate limit (5/hr/IP), the need to poll fetch_answer, and the variable response time (minutes, hours, or days). This is rich, actionable 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 exceptionally concise: two sentences that cover purpose, return value, rate limit, polling mechanism, and timing. Every word earns its place, and key information is front-loaded.

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

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

Given the tool's complexity (3 params, no output schema, no annotations), the description covers the main behavioral aspects well—purpose, async flow, rate limiting, and polling. However, it leaves 'from' and 'context' unexplained, which is a notable gap for a tool with such a small parameter set.

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

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

Schema description coverage is 0%, so the description must compensate for the three parameters. It implicitly clarifies 'question' by saying 'Submit an async question', but provides no explanation for 'from' or 'context'. The parameter meanings beyond the names are largely unclear.

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

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

The description uses the specific verb 'Submit' and identifies the resource as 'an async question to kapoost', clearly distinguishing it from siblings like fetch_answer (for polling) and submit_answer (for writing answers). It also mentions returning an ID, which clarifies the output.

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 instructs to 'Poll fetch_answer later', naming the complementary tool and indicating the async workflow. It also sets expectations that kapoost answers on his own schedule, but does not explicitly state when not 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 the full burden. It discloses the validation step, the output structure, and a rate limit, but it does not clarify whether the tool creates a persistent session or how it handles invalid codes. This is a moderate disclosure.

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

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

The description is a single, compact sentence that front-loads the action and specifies the output components. No redundant information is present; every word 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 tool with one parameter and no output schema, the description covers the input's purpose and outlines the output's composition. It lacks explicit error handling and side-effect transparency, but the core workflow is adequately described.

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 only defines 'code' as a string, but the description explains it is a 'Polish poetry session code' and that it is validated. This adds essential semantic context beyond the raw schema, which is necessary given 0% 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 names a specific action sequence: validate the session code, then emit a full team briefing with enumerated components (guardian, style, personas, skills, persist block). This clearly distinguishes it from the sibling tools, which are mostly list/get/read/write operations.

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 the tool is used for bootstrapping a Polish poetry session but does not explicitly state when to use it or mention alternatives. The rate limit adds operational context, but there is no when-not or exclusion guidance.

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

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

No annotations are provided, so the description carries the full burden. It discloses the auth requirement and ownership constraint, which are essential for a destructive operation. It doesn't mention irreversibility or response details, but core guidance is present.

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

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

The description is a single, front-loaded sentence with no filler. Every word 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 tool with one parameter and no output schema, the description covers purpose and auth. It doesn't detail success/failure responses, but this is a minor gap given the tool's simplicity.

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 0%, so the description must explain the parameter. 'By slug' clearly indicates the slug identifies the skill to delete, adding meaning beyond the raw string type.

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

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

The description states 'Delete a skill by slug' with a specific verb, resource, and identifier. This clearly distinguishes it from sibling tools like get_skill and 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?

The owner-only requirement and auth header provide clear context for when to use the tool. It doesn't explicitly mention alternatives or when not to use, so it stops short of a 5.

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 of behavioral disclosure. It reveals a side effect (marking the question as fetched on first successful return) and a rate limit (30/hr/IP), which are important operational details beyond the basic fetch action.

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, front-loaded with the core function, followed by side effect and rate limit. Every sentence adds value 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?

The description explains the polling behavior and side effects, but does not describe the return value structure or behavior when no answer is yet available. Given there is no output schema, this would be helpful. However, it is a simple tool and the description is adequate for basic use.

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

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

The input schema has one parameter 'id' with 0% description coverage. The description implies the id refers to an ask_human question, but does not explicitly specify its format or how to obtain it. This provides some context but not full compensation for the missing schema description.

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

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

The description clearly states the tool is used to poll for an answer to an ask_human question, which is specific and distinguishes it from sibling tools like ask_human (which initiates the question) and submit_answer (which submits an 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?

It implies the tool should be used after asking a question and before an answer is available, but it does not explicitly mention alternatives or exclusions. The context is clear enough for an agent to infer the usage timing.

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 discloses that the tool returns current status and, when done, returns all persona voices. However, it doesn't state whether polling is non-blocking, safe to call repeatedly, or what happens on error. Some key behavioral context is missing.

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

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

The description is three short sentences, front-loaded with the core purpose ('Poll a narada job by ID'), followed by status values and return behavior. Every sentence earns its place with no redundancy or 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?

For a simple one-parameter polling tool, the description covers purpose, statuses, and return value. It lacks explicit guidance on repeated polling or error handling, but the term 'poll' and status list imply the necessary usage pattern. Overall, it's reasonably complete given the tool's simplicity.

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 0%, with only a single required 'id' string. The description compensates by specifying the ID refers to a narada job. This adds essential context beyond the schema's bare type definition, though no further parameter details are provided.

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 ('Poll a narada job by ID') with a specific verb and resource. It doesn't explicitly name sibling tools like run_narada or fetch_answer, so it lacks direct differentiation, but the verb 'poll' and 'narada job' make the purpose 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 status list (pending, running, done, failed) implies this is used after starting a job with run_narada, but the description doesn't explicitly say when to use this tool versus alternatives. No when-not-to-use guidance is provided; usage is only implied.

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 a side effect (recording a profile-view event), which is useful behavioral context. However, with no annotations, it does not cover other aspects like permissions, reversibility, or the meaning of 'browsing cheatsheet.'

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 concise sentences, each serving a purpose: describing the output and noting the side effect. No wasted words or redundant details.

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 zero-parameter tool with no output schema, the description provides a high-level summary of the returned data and notes the side effect. It is reasonably complete but leaves the 'browsing cheatsheet' vague and doesn't elaborate on the profile-view event's implications.

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 zero parameters, and the schema coverage is 100% vacuously. According to the baseline for 0 params, a score of 4 is appropriate; no additional parameter information is 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 clearly states the tool returns author identity, bio, and a browsing cheatsheet, and records a profile-view event. This distinguishes it from sibling tools like get_persona or about_humanmcp, though it doesn't explicitly differentiate.

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

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

No guidance is provided on when to use this tool versus alternatives. The description lacks any mention of prerequisites, exclusions, or recommended contexts.

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 responsibility. It uses 'Return' which implies a read operation, but does not disclose whether the certificate is generated or retrieved, what input format is expected, or any side effects. The description lacks sufficient behavioral detail.

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

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

The description is a single concise sentence that is front-loaded with the primary action. No wasted words.

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

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

Despite the tool's apparent simplicity, the description is too minimal: it does not explain what a certificate contains, what 'piece' refers to, or how to interpret the output. With no output schema or annotations, the agent has insufficient 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 schema provides no description for 'slug', and the tool description also does not explain what slug represents or its format. The phrase 'for a piece' hints at the purpose but does not explicitly map slug to the piece identifier.

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

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

The description clearly states the tool returns a formatted certificate for a piece, using a specific verb and resource. It does not explicitly differentiate from sibling tools like verify_content or request_license, but the purpose is unambiguous.

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

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

No guidance is provided about when to use this tool versus alternatives such as verify_content or request_license. There is no mention of prerequisites or context.

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 burden of disclosing behavior. It explicitly reveals that the tool is session-gated, that Hodor bypasses this, and that guardian rules always apply, which is meaningful access-control behavior beyond the schema. It does not elaborate on what 'guardian rules' entails or the response format, but for a simple getter it provides solid transparency.

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 the core action and identifier, followed by the auth nuance. Every sentence earns its place with no 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 two-parameter getter with no output schema, it gives the lookup key, auth rule, and an exception. It does not describe errors or the exact response shape, but the phrase 'full prompt' already signals the return value; remaining gaps are minor.

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 50%: session_token already has a detailed schema description, and the tool description mostly restates that. The only addition for slug is that lookup happens 'by slug', compensating somewhat for the schema's bare string type. Overall the description adds modest meaning but does not fully enrich 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 opens with a specific action and target ('Return one persona's full prompt by slug'), which clearly identifies the resource and lookup key. This distinguishes it from siblings like get_persona_journal or list_personas because it specifies 'full prompt' and 'by slug'.

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

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

It explains the authorization context: the tool is session-gated, has a Hodor exception, and tells callers when to pass session_token instead of an Authorization header. It does not name alternative tools or state when not to use it, so it falls just short of 5.

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 of behavioral disclosure. It reveals that the journal is private, a feedback loop, and restricted to the owner. This meaningfully communicates access control and intent, though it doesn't detail response format or behavior for unauthorized access.

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 short sentences that front-load the action and resource, followed by essential access context. 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 one-parameter read tool, the description covers purpose, resource, and authorization. It omits return-value details, but given the low complexity and absence of an output schema, the description is largely complete.

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

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

Schema coverage is 0% and the description does not explain the 'slug' parameter. The context implies slug identifies the persona, but the agent must infer this; no format, source, or lookup semantics are provided.

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 starts with a specific verb 'Read' and identifies the exact resource: 'a persona's raw reflection journal'. This clearly distinguishes it from sibling tools like get_persona or get_author_profile, which target different data objects.

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

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

The description gives explicit when-not guidance: 'Owner-only' and 'not for external callers'. It does not name an alternative tool to use instead for public persona information, so it stops short of providing a full alternative recommendation.

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 discloses the session-gating requirement, the guardian bypass, and the authentication fallback, which are important behavioral traits. It doesn't mention error conditions or rate limits, but for a simple retrieval tool, the key behaviors are covered.

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 filler. The essential action and the most critical edge case (session-gating) are front-loaded. Every sentence serves a 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?

The description explains how to call the tool, including authentication nuances, and clarifies the resource. It doesn't mention what the response contains beyond 'full body' or handle not-found errors, but for a simple get operation with an existing output schema absent, this is mostly complete. The lack of an output schema is not the description's fault.

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 describes session_token fully (as optional and for header fallback), but slug has no description in the schema. The description clarifies that slug is the identifier by which the skill is fetched. It also reinforces session_token's purpose, complementing the schema description. With 50% schema coverage, the description adds meaningful value.

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

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

The description states a specific action ('Return'), a specific resource ('one skill's full body'), and the criteria ('by slug'). It clearly differentiates from siblings like list_skills (which lists many) and upsert_skill/delete_skill (which modify).

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 usage context: mentions session-gating and a bypass for -public suffixed skills. Also explains when to pass session_token (if client can't set Authorization header). While it doesn't explicitly state when to use this over list_skills, the intended use is implicit from 'by slug'.

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 a key behavioral trait: silent truncation past 280 characters. With no annotations, the description carries the full burden, but it omits details like authentication requirements, error handling, or comment visibility, making this only partial transparency.

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, front-loaded with purpose and a concise behavioral note. Every word earns its place, with no fluff or redundancy.

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

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

The tool is a mutating operation with no annotations and no output schema. The description gives the core purpose and limit behavior, but is incomplete regarding parameter semantics (especially 'from'), potential side effects, and failure modes. It does not provide enough context for an agent to confidently use the tool without further inference.

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 0%, leaving all three parameters undocumented. The description hints at 'text' being the comment and 'slug' identifying the piece, but 'from' remains ambiguous. The description does not adequately compensate for the missing 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?

The description clearly states the tool's verb ('attach') and resource ('a piece kapoost has published'), and adds a constraint (short comment ≤280 chars). It distinguishes from sibling 'leave_message' by focusing on comment vs message, though not explicitly.

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: attach a comment to a published piece. However, it gives no explicit 'when to use' context or alternatives, and does not address exclusions or prerequisites beyond the character limit.

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 present, so the description carries the full burden. It discloses the critical constraints (context required, contact optional for replies), but does not mention other behavioral aspects such as return values, length limits, or any side effects beyond sending.

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, front-loaded with the action and key requirements. Every word adds value, with no extraneous 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?

For a tool with 5 parameters and no output schema, the description explains only two parameters and lacks return-value details. It is adequate for a simple messaging tool, but the gaps in parameter semantics and behavioral disclosure prevent a higher score.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the meaning of 'context' and 'contact', but omits 'text', 'from', and 'regarding'. Additionally, it only highlights context as required, while the schema also requires text, which may mislead the agent.

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 ('Send kapoost a longer message') and identifies the resource (kapoost). The word 'longer' differentiates it from sibling tools like leave_comment, implying a distinct use case.

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 clear guidance on prerequisites: context is required, contact is optional but necessary for a reply. It implies a longer message use case compared to leave_comment, but does not explicitly name alternatives or exclusion 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 responsibility for disclosing behavior. It mentions that the readable-column depends on caller_kind/caller_id and audience, which hints at access control, but it's cryptic and does not explain side effects, permissions, or return behavior. This is insufficient for a read/list tool with zero annotation support.

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 (two sentences) and avoids redundant filler. However, the second sentence is cryptic and not optimally structured—'Readable-column reflects...' sounds like a field name but is not explained, making it less effective. Still, it earns points for 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?

There is no output schema, no annotations, and the input schema is bare. The description provides a list of artifact types and one filter hint, but lacks details on return structure, filtering semantics, pagination, error cases, or how caller parameters interact. The cryptic 'readable-column' further reduces completeness. For a simple listing tool, this is under-specified.

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

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

Schema description coverage is 0%, so the description must compensate. The description explains blob_type as a filter, which adds some meaning. However, caller_id and caller_kind are not explained at all beyond the vague 'readable-column' reference. The description fails to give a clear semantic role for two of the three parameters, leaving the agent to guess.

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 a specific verb ('List') and resource ('typed data artifacts') with enumerated types (images, contact, vectors, documents, datasets, capsules), which distinguishes it from sibling list tools like list_collection or list_content. The 'readable-column' phrase adds a unique function but is vague and could confuse rather than clarify.

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: use this to list typed data artifacts and filter by blob_type. However, it does not explicitly state when to use this versus other listing tools, nor does it provide exclusions or alternative tool names. The filter instruction gives some guidance, but it's minimal.

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 does disclose the access model (public always, members-only after session activation) which is a behavioral constraint. However, it does not explicitly state that the operation is read-only or non-destructive, and there is no mention of error conditions or rate limits. For a list operation, the absence of side-effect warnings is less critical, but the description could be more explicit about safety.

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

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

Two concise sentences, with the core purpose front-loaded. The first sentence states exactly what is listed, and the second adds a critical access condition. No redundancy or filler. Padding is minimal and every word contributes to understanding.

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 tool with one optional parameter and no output schema, the description covers the essential context: what is listed, the ownership distinction, and the session-token requirement for restricted items. It does not specify the return format or pagination, but given the low complexity and that sibling tools likely share conventions, this is adequate. A more complete description might mention whether results are sorted or limited, but that is a minor gap.

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, session_token, is fully described in the input schema (100% coverage). The description adds no additional meaning beyond the schema, so it meets the baseline for when schema covers everything. No extra value is provided, but none is 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 the tool lists works 'kapoost owns but did NOT create', which is a specific and distinctive purpose. It also mentions the public-vs-members-only visibility split, making it stand out from sibling list tools like list_content or list_blobs. The verb 'List' and the resource are unambiguous.

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

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

The description gives a clear condition for usage: it lists works not created by the owner, and notes that members-only items appear only after session activation. This implies when to use it (when you need such works) but does not explicitly name alternatives or state when not to use it. The session activation context is a useful prerequisite signal, so this is above average but not explicit about exclusions.

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 burden of behavioral disclosure. It communicates a read-only listing operation and specifies the output fields. It doesn't mention pagination or sorting, but for a simple list tool the key behavior is clear.

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

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

The description is a single sentence, front-loaded with the verb and resource, and contains no redundant words. Every element contributes to understanding the tool's 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?

For a simple list tool with two optional parameters and no output schema, the description covers the essential purpose and output fields. However, it lacks details on filter value formats and potential pagination; despite this, the tool is straightforward enough that the description is mostly complete.

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

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

The schema provides two string parameters (tag, type) with no descriptions and zero enums. The description only calls them 'optional type/tag filters,' which offers minimal added meaning. It doesn't explain valid values or formats, so with 0% schema description coverage, this is insufficient compensation.

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

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

The description clearly states the tool's action (list) and resource (published pieces), enumerating the returned fields (slug, title, type, access, tags). It distinguishes itself from sibling list tools by specifying 'content' and its output scope.

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 indicates the tool lists published content and supports optional type/tag filters, providing clear context for when to use it. It doesn't explicitly mention alternatives (e.g., read_content for a single piece), but the verb 'list' and fields imply a list vs. detail usage.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that full prompts unlock after bootstrap_session, which is useful context, but it does not mention authentication, rate limits, or the behavior before bootstrap_session. This adds some transparency but leaves significant gaps.

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

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

The description is a single concise sentence that front-loads the action and resource, with every word contributing meaning. There is no wasted text, and the structure is perfectly appropriate for a simple list 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?

For a zero-parameter list tool with no output schema, the description adequately covers the operation, returned fields, and a key behavioral dependency. However, it does not clarify what happens before bootstrap_session (e.g., whether results are partial or error), which would make it fully complete.

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

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

The input schema has zero properties, and the baseline for 0 parameters is 4. The description mentions the return fields but no parameter semantics are needed, so the baseline 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?

The description uses the specific verb 'List' and specifies the resource 'persona' along with the returned fields (slug, title, role). This clearly distinguishes it from sibling tools like get_persona, which fetches a single persona, making the purpose 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 implies that full prompts are available after bootstrap_session, but it does not explicitly state when to use this tool versus alternatives such as get_persona or other list tools. The usage context is present but not fully elaborated with exclusions or alternative recommendations.

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 behavioral burden. It does disclose the lookup strategy ('Tries piece then collection'), which adds useful context. Yet it leaves gaps: what happens if both piece and collection match, whether results are merged, and what the response looks like. This partial disclosure is better than nothing but not fully transparent.

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

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

Two sentences, zero wasted words. The action is front-loaded, examples are parenthetically useful, and the fallback note is compact. Excellent conciseness.

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 list operation, the description covers purpose, parameter meaning, and a behavioral nuance. It omits return shape or error specifics, but given the lack of an output schema and the tool's simplicity, it is largely complete.

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

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

The description clarifies that 'slug' refers to an artwork slug, providing meaning beyond the bare string schema. However, it does not explain how the slug relates to the 'piece then collection' fallback or specify any format constraints. Schema coverage is 0%, so the description partially compensates but leaves ambiguity.

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

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

The description uses a specific verb 'List' with a clear resource 'provenance items', enumerates example items, and scopes to an artwork slug. It distinctly describes a list operation, differentiating it from the sibling read_provenance, and the 'Tries piece then collection' clause adds a unique search scope.

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

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

Usage is implied: use this tool to list all provenance items for a given artwork slug. However, it does not explicitly contrast with read_provenance or get_certificate, and gives no exclusions or alternative scenarios. Without an explicit when-to-use guide, the agent must infer from context.

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 burden of behavioral disclosure. It discloses that the operation is public, requires no bootstrap, and returns a comprehensive set of skill tags with slugs per group, which implies a read-only, unfiltered listing. It stops short of explicitly stating no side effects, but the provided context is meaningful.

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, each adding unique value: the first explains what is listed and the grouping detail, the second clarifies access requirements. There is no 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 zero-parameter tool with no output schema, the description covers the essential purpose and access constraints, and hints at the response structure ('slugs per group'). It doesn't specify the exact return format, but this is a minor gap given the tool's simplicity.

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 zero parameters, so the input schema trivially covers everything. The description correctly adds no further parameter details, and the baseline of 4 applies since there is nothing to clarify.

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 provides an 'Index of every skill tag in use, with slugs per group,' which specifies both the resource (skill tags) and the output detail (slugs per group). This distinguishes it from siblings like list_skills by focusing on tags/groups, though it doesn't explicitly name an alternative.

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 adds 'Public — no bootstrap required,' implying it is safe to call without authentication or setup. However, it doesn't explicitly state when to prefer this over sibling list tools like list_skills or list_content, so usage guidance remains implied rather than explicit.

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 burden. It accurately describes the output fields and filter options, which is sufficient for a read-only list operation. It does not explicitly state read-only, but 'list' implies a safe read, and there are no destructive behaviors to disclose.

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

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

The description is a single efficient sentence covering the resource, returned fields, and filter options. Every word earns its place with no redundancy.

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

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

Given no output schema, the description adequately explains what the tool returns (fields) and how filters work. The array structure is implied by 'list', and the optionality is clear. Minor gap is not specifying how filters combine (AND/OR), but this is a simple 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 schema properties have no descriptions, but the description explicitly identifies both 'category' and 'tag' as optional filters. This adds meaningful semantics beyond the bare schema, explaining how the parameters are used.

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

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

The description states the action 'List' with resource 'skills' and specifies the returned fields (slug, category, title, tags). It also mentions optional filters, distinguishing it from siblings like get_skill (single skill) and suggest_skills (recommendations).

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 context is clear: use this to list all skills or apply category/tag filters. No explicit alternatives are mentioned, but for a simple list tool, the use case is obvious. Lacks a direct 'when not to use' but not necessary given the straightforward purpose.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose the auth/session requirements per skill (the -public suffix bypass). However, it omits return format, pagination, error behavior, and any side effects. For a bulk fetch, this leaves significant gaps.

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

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

The description is two concise sentences that front-load the primary action and then provide the key gate condition. There is no filler, and every sentence earns its place. It could be slightly more structured, but it is 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?

For a bulk-fetch tool with no output schema, the description does not specify the return format, error cases, pagination, or limits. The auth requirement is covered, but an agent would likely need additional assumptions about the response structure. Adequate but incomplete.

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 50%; the description adds meaning to both parameters. It clarifies that `name` is the group name and explains when `session_token` is needed (unless the skill name ends with -public). This goes beyond the schema, but it does not elaborate on name constraints or return shape, so it only partially compensates for the coverage gap.

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 (bulk-fetch) and resource (skills tagged by group name), which distinguishes it from get_skill (single skill) and list_skills (general listing). However, it does not explicitly name sibling tools, so it misses the top score for explicit 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?

The description provides the context of the bootstrap gate (when session is needed), which is a usage constraint, but it does not explicitly say when to prefer this tool over alternatives like list_skills or get_skill. Usage guidance is implied rather than 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?

The description discloses important runtime behaviors: requires Bearer token, friend token scoping with not_found for out-of-scope/private slugs, and offline response. These are beyond the basic schema. Missing details like edit token access to private documents or invalid-token errors, but given no annotations, this is solid.

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

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

The description is three sentences, front-loaded with the main action. Each sentence adds critical info: purpose, auth, and edge-case behavior. 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?

The tool is simple with one parameter, but there is no output schema. The description explains offline behavior but not the success response format or error behaviors for invalid tokens/edit token access to private items. This leaves some gaps for an agent to understand expected outputs fully.

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 0% parameter description coverage, so the description must compensate. It only says 'by slug', which maps doc_slug to its concept, but adds no detail about slug format, where to find it, or constraints. This is minimal semantic value; the description does not sufficiently clarify the parameter beyond its name.

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 fetches a single document by slug from a specific resource ('kapoost's vault'). It distinguishes itself from sibling tools like list or search by focusing on one document and requiring a slug. The verb 'Fetch' and resource 'document' are specific and unambiguous.

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

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

The description implies usage: when you have a document slug and the proper authorization token. It also clarifies friend token limitations and offline behavior, which guides when to use it. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.

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 behavioral disclosure. It covers authorization requirements (Bearer edit or friend token), token scoping behavior, visibility of private documents, offline response format ({status:offline}), and the returned fields. This is comprehensive transparency.

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

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

The description is compact yet complete, front-loading the core purpose before covering auth, args, return format, and offline behavior in a few sentences. Every part contributes essential information with 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?

For a list tool with no output schema and no annotations, the description provides all required context: purpose, auth, filtering, pagination, return structure, and offline handling. It is fully sufficient for an agent to invoke correctly.

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

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

The input schema has no descriptions, so the description must explain parameters. It does so thoroughly: doc_type is a string filter with examples, limit is an integer 1-200 defaulting to 50, and offset defaults to 0. This fully compensates for the 0% 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 opens with 'Enumerate vault documents without FTS — for browsing by type or paginating,' using a precise verb ('enumerate') and resource ('vault documents') while explicitly distinguishing it from search functionality. The 'without FTS' qualifier clearly differentiates this from sibling search 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 phrase 'for browsing by type or paginating' gives clear use cases, and 'without FTS' implies that search should be used for full-text queries. It also notes that friend tokens see only their scoped doc_types and access:private is invisible, guiding when access might be restricted. It does not explicitly name the sibling search tool, but the distinction is evident.

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

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

With no annotations provided, the description carries the full burden and excels. It discloses auth bearer token types (edit or friend), friend-token scoping (only their scoped doc_types, access:private invisible), the exact return structure ({status, results:[...], summary}), and the offline behavior ({status:offline}). This is exceptional transparency.

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 pack a dense yet well-organized spec: purpose, auth/scoping, return structure, and offline behavior. There is zero filler, and all claims earn their 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?

The description covers auth, scoping, output structure, and the offline error state, which is impressive given there is no annotations or output schema. However, complete parameter documentation is absent for a 4-parameter tool, so the description is not fully complete on its own.

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 four parameters with zero descriptions, and the tool description does not explain any of them. It never mentions limit, doc_slug, doc_type, or query's specific role beyond the general search concept. The agent is left to infer parameter meanings from names alone, which is a significant gap for correct invocation.

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

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

The description opens with 'Full-text search (BM25 over SQLite FTS5) on kapoost's local vault corpus,' which specifies the exact operation (search), technology (BM25/FTS5), and target resource (kapoost vault). It also differentiates from sibling tools like mysloodsiewnia_list and mysloodsiewnia_get by emphasizing full-text semantic search rather than listing/retrieval.

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 indicates the tool is for full-text search of the corpus, providing clear context for when to use it. It includes authorization requirements and friend-token scoping rules, which are critical for safe invocation. However, it does not explicitly mention alternatives or exclusions relative to sibling tools, so it stops short of a complete usage guide.

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 operation is read-only, lists the exact return fields, explains offline semantics, and specifies the required Authorization header. This is comprehensive for a status probe.

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, front-loaded with the core purpose, and includes only essential information: what it does, what it returns, one critical behavioral note, and the auth requirement. No waste.

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

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

For a parameterless status tool, the description is largely complete: it defines the output shape, gives offline behavior guidance, and notes auth. However, it does not explain the meaning of the 'degraded' status, which is a minor gap in the status enum semantics.

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, so schema coverage is 100% by definition. Per the rubric, 0 params yields a baseline of 4. The description doesn't need to add parameter details, and it doesn't.

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 function as a 'read-only liveness probe' on a specific vault, with a specific verb and resource. It distinguishes itself from sibling tools like get, list, search, and write by focusing on health/status rather than data operations.

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 clear context for use as a liveness probe and gives important behavioral guidance ('Offline is a stable state — retry later, don't escalate'). However, it does not explicitly mention alternative tools or when to prefer this over sibling status-related operations, so it misses the 'explicit when/when-not/alternatives' level.

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 carries the transparency burden. It discloses idempotency (op_id is dedup key), the permanent unavailability of delete, the 1-hour TTL for session tokens, and enumerates all possible response envelopes including error cases like vault_timeout and payload_too_large. This is exceptionally transparent behavior disclosure.

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

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

The description is a single dense paragraph with no fluff; every sentence provides operational value. However, it could benefit from structured bullets or sections (auth, args, response envelopes) to improve readability for an AI agent. Given the complexity, the length is warranted, but the structure could be clearer.

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, the description is remarkably complete. It covers authentication details (including two token retrieval methods), ownership restrictions, idempotency semantics, deletion policy, and every possible response envelope. No output schema exists, so the description fully explains return values, making it self-sufficient 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 description coverage is 0%, so the description must compensate. It lists all parameters (doc_type, title, body, source_path, meta) and adds constraints: body ≤100 KiB, source_path and meta are optional. It also notes meta is an object. However, it does not elaborate on allowed doc_type values or the internal structure of meta, leaving some semantics under-specified.

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

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

The description opens with 'Ingest a new document into kapoost's vault (wave 2)', which clearly identifies the action (ingest/write) and the target resource (kapoost's vault). It also distinguishes itself from sibling tools like mysloodsiewnia_get, list, search, and status, making its role as the write operation explicit.

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 strong context by stating it is OWNER-ONLY and detailing the required Authorization: Bearer <owner token>. It explains how to obtain the token via bootstrap_session or shell command. However, it does not explicitly mention when to use this tool versus alternatives or when not to use it, though the context is clear.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behaviors: no LLM cost, no rate limit, nothing recorded, no narada ID, no journal feedback, and session-gating. This gives the agent a clear safety and side-effect profile.

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 compact sentences front-load the core purpose, then add behavioral caveats, then usage guidance. No filler; 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?

It covers purpose, usage, and behavioral side effects. It vaguely references what is returned (panel + prompts) but does not detail the panel structure or how session_token is used beyond 'session-gated'. For a tool with no output schema and a single required param, this is adequate, though a bit more detail on the returned panel would round it out.

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 67% (personas and session_token are described, context is not). The description adds some meaning by implying 'persona's prompts' relate to the personas param, but it does not explain the required context parameter at all. It sits in the middle range and doesn't fully compensate for the missing schema description of context.

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

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

The description opens with a specific verb and resource: 'returns the panel plus each persona's ready-to-run SYSTEM/USER prompts'. It clearly differentiates from the sibling run_narada by explaining it runs offline. This is unambiguous and non-tautological.

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?

'Prefer this over run_narada when...' explicitly names the alternative and gives concrete conditions (subagents can read server-inaccessible material, or server lacks an API key). It also implies when not to use it, making the routing decision explicit.

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 must carry the transparency burden. It discloses that returns are text or base64-encoded and that access depends on audience unless public, which is helpful. However, it does not explain error behavior, how caller_id/caller_kind affect access gating, or any other side effects, leaving gaps in behavioral understanding.

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, front-loaded with the core action and resource, and every word adds value (slug, return type, access gating). There is no unnecessary verbosity or repetition of schema fields.

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

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

The tool is simple (3 params, no output schema), and the description covers the main purpose, return format, and access control. However, the missing parameter semantics for caller_id/caller_kind and lack of return structure/error details make it only minimally complete for an agent to invoke correctly in all cases.

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

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

Schema description coverage is 0%, so the description must explain all parameters. It explicitly mentions 'slug' as the lookup key, but caller_id and caller_kind are not mentioned at all, leaving them unexplained. The description only partially compensates for the complete lack of 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?

The description opens with 'Read one blob by slug', which uses a specific verb and resource, clearly distinguishing it from list_blobs (which lists blobs) and other read tools targeting different resources. It also specifies the output type, making the purpose 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 intended usage is implied by 'Read one blob by slug' and the access-gating note, but there is no explicit comparison to sibling tools like list_blobs or read_content, nor any 'when not to use' guidance. This leaves the agent to infer the scope from the resource name.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses access constraints and the nature of the return, which is useful. However, it omits other behavioral traits like error handling, rate limits, or confirmation that the operation is non-destructive. This is 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?

The description is two concise sentences. It front-loads the core purpose and then adds the access constraint. There is no fluff or redundant information; 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?

The tool has no output schema and no annotations, so the description must cover return format and usage details. It mentions a full record and dossier count but doesn't describe the record structure or how errors are surfaced. The slug format and auth behaviors are also not covered. For a simple read this is minimal but missing critical details an agent would need to call it 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 50%: only session_token has a description in the schema. The required 'slug' parameter has no description, and the tool description does not explain what a slug is or how it identifies the item. The session requirement is hinted at through 'members needs session', but the description fails to compensate for the undocumented slug parameter, which is essential for calling the tool.

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

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

The description clearly states the action ('read') and the resource ('collection item'), and specifies the output includes a full record and a dossier count. It is specific and avoids tautology, but it doesn't differentiate this tool from siblings like read_content or read_blob, so it misses a point for lack of distinction.

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 access gating information ('private is never visible, members needs session'), which implies when the tool can be used, but it doesn't explicitly state when to choose this over alternatives like list_collection. It provides context but no exclusion or alternative routing.

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 burden of behavioral disclosure. It does disclose a key behavior: locked pieces return a hint pointing to request_access, which is valuable. However, it does not mention error behavior, authentication requirements, or what exactly is returned (full content vs. metadata), leaving some gaps.

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

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

The description is two sentences, front-loaded with the main action. The second sentence adds essential edge-case behavior (locked pieces) without redundancy. Every word earns its place, and it is appropriately sized for a simple 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?

For a tool with a single required parameter, no output schema, and a clear primary purpose, the description is largely complete. It covers the normal path (public piece) and the special case (locked piece). It does not specify response format or behavior when the slug is invalid, but these are minor gaps given the tool's simplicity.

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 only defines 'slug' as a string with no description. The description compensates by explaining that the slug identifies a piece of content: 'Read a public piece by slug.' This clarifies the parameter's purpose, though it does not detail slug format or examples.

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

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

The description states a specific verb+resource: 'Read a public piece by slug.' This clearly distinguishes it from siblings like list_content (which lists content) and verify_content (which likely verifies). The addition of 'public' and the locked-piece behavior further clarify its scope.

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

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

The description implies when to use this tool: when you need to read a specific public piece identified by a slug. It also provides a guide for locked pieces by pointing to request_access as an alternative. However, it does not explicitly contrast with siblings like list_content or mention prerequisites beyond having a slug.

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 hints at output containing resolvable file URLs but doesn't disclose read-only behavior, error handling, or prerequisites beyond the parameter names. The description is too thin to provide meaningful behavioral transparency.

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

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

Two sentences, zero fluff, and front-loaded with purpose. Ideal conciseness for a simple read operation.

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

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

The description lacks key context: no mention of what happens if the item isn't found, auth requirements, or any side effects. Without annotations, a simple read tool should at least clarify its read-only nature and expected output.

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 has no descriptions and the description adds no meaning to 'slug' and 'id' beyond restating their requirement. No parameter semantics are clarified.

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

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

The description clearly states the tool returns one provenance item, using the verb 'Return' and specifying the resource. The word 'one' distinguishes it from list_provenance, though it doesn't explicitly name alternatives.

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

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

No guidance is given on when to use this tool versus alternatives like list_provenance. It only restates required parameters, which is already in the schema, without any context for appropriate 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?

With no annotations, the description carries the full burden. It discloses session-gating, which is a behavioral trait, but does not explicitly state read-only behavior, return format, pagination, or error behavior. No contradiction with annotations (none 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?

One concise sentence with a front-loaded action ('List memories'), an optional condition ('optionally substring-filtered by query'), and a session context remark. No redundant wording; every phrase contributes.

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 read-list tool with no output schema, it covers the main purpose and query filtering, but omits details on 'limit' (e.g., default, max), response format, and potential errors. It could be more complete given low schema coverage.

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 25% – only session_token has a description. The description adds meaning for 'code' (memories under the code) and 'query' (substring-filtered), but does not explain 'limit'. It partially compensates for the coverage gap but not fully.

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

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

The description states 'List memories saved under the given code' – a specific verb and resource. It also mentions 'Session-gated for symmetry with remember,' which differentiates it from other listing tools like list_blobs or list_collection by tying it to the remember counterpart.

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

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

It clearly implies when to use it (to retrieve memories saved under a code, optionally filtered by query) and references 'symmetry with remember' as context. It does not explicitly list exclusions or alternatives, but the action and session requirement are clear.

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

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

With no annotations, the description must disclose behavioral traits. It states the core mutation (appends to the persona's journal) and the owner-only permission, but does not elaborate on reversibility, side effects, or whether the operation is synchronous. This is adequate but not detailed.

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 compact sentences that front-load the main action and then provide the effect and permission. No wasted words; every sentence contributes 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?

The tool has no output schema and sparse annotations, so the description carries the burden. It covers purpose, trigger, effect, and permission, but omits parameter meanings and any note about return values or errors. Adequate for a simple tool, but not fully complete.

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

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

The schema has no descriptions for any of the three required parameters, and the description does not explain them. While the context implies narada_id relates to the recommendation, persona_slug to the persona, and error_context to the rollback reason, the mapping is left to inference. This is a significant gap.

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 action: ask a persona to write a lesson-for-self after a rolled-back narada recommendation. It also specifies the effect (appends to the persona's journal) and a permission constraint (owner-only), making it distinct from sibling tools like get_persona_journal or 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?

The description gives a specific trigger context ('after a rolled-back narada recommendation') and an access restriction ('Owner-only'). It does not explicitly mention alternatives or exclusions, but the context is clear enough for an agent to decide when to use this tool.

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 burden of behavioral disclosure. It does reveal that the operation is session-gated and that memory is shared among code holders, which adds context beyond the schema. However, it leaves out important behaviors such as whether the note is appended or overwritten, what happens if the code is invalid, or any authentication requirements beyond the initial bootstrap.

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 concise sentences with no redundant words. The main action is front-loaded, and the session-gating constraint is stated immediately after the 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?

For a tool with 5 parameters, 2 required, and no output schema, the description is too sparse. It does not mention what the tool returns, how parameters like 'from' and 'tags' are used, or any error conditions. The agent is left without enough context to confidently invoke the tool correctly in all cases.

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 20% (only 'session_token' has a description). The tool description connects 'session code' to the 'code' parameter and 'note' to 'text', but it does not explain the semantics of 'from' or 'tags'. This is insufficient compensation for the low schema coverage, leaving the agent to guess about those 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 uses a specific verb ('persist') and resource ('note') tied to a 'session code', clearly distinguishing this from sibling tools like 'recall' (which presumably reads notes). It also explicitly notes session-gating, making the operation's scope unambiguous.

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

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

The description gives a clear precondition ('bootstrap_session first') and a usage context ('Callers sharing the code share the memory'), implying when to use the tool. However, it does not explicitly mention when not to use it or name 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?

No annotations are provided, so the description must disclose behavioral traits. It only states what the tool returns, not whether it is read-only, requires authentication, has side effects, or how the response is structured. The verb 'Get' implies a safe read, but this is not explicit, and no additional behavioral context is given.

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

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

The description is a single, concise sentence that front-loads the purpose. It lists specific detail types, providing useful information without any wasted words. It is appropriately sized for the tool's simplicity.

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 one-parameter getter with no output schema, the description gives a reasonable overview of what is returned (types of gate details). However, it lacks behavioral details such as whether access is actually requested or just details are returned, and it doesn't specify the response format or error conditions. It is minimally complete but has 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?

Schema coverage is 0%, so the description must compensate for the single 'slug' parameter. The description never mentions 'slug' or explains how to identify the locked piece. It is only implied that the slug refers to the locked piece, leaving the agent to infer the parameter's meaning without clear guidance.

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

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

The description clearly states the tool's purpose: to retrieve gate details for a locked piece, listing specific types of details (challenge question, manual-review flow, time-lock countdown, payment terms, trade rules). The verb 'Get' and resource 'gate details' are specific, though it does not explicitly distinguish from sibling tools like request_license.

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: when a piece is locked and one needs gate details. However, it provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The context is clear but understated.

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 two behavioral traits beyond the schema: the creation of an audit-log entry and the strict validation that caller_id must not be whitespace-only. Given that no annotations are provided, this adds some context, but it lacks other useful information like permissions, reversibility, or potential side effects beyond the audit log.

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

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

The description is extremely concise: two sentences, front-loaded with the core purpose, no redundant phrasing. It even packs in a behavioral constraint without 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?

For a tool with three required parameters and no output schema or annotations, the description covers the basic action and one side effect but misses parameter explanations and return value structure. It is minimally viable but has clear gaps, making it a 'minimum viable' score.

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

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

Schema description coverage is 0%, so the description must compensate. It only explains caller_id (required, whitespace rejected), but leaves slug and intended_use completely unexplained. This is insufficient for three required parameters, especially without any 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?

The description clearly identifies the tool's purpose: to declare intended use for a piece and receive licensing terms plus an audit-log entry. It uses specific verbs and resources, and while it doesn't name alternatives, the purpose is distinct enough from siblings like 'request_access'.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or when another tool should be used instead. The only usage hint is the caller_id requirement, which is about parameter usage, not tool selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the job is asynchronous, that it routes to 3-5 personas, which models are used for different voice types, that the return value is a job ID for polling, and that passing `personas` bypasses the router. This is substantial and honest behavioral transparency.

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 carry all essential information without filler. The core async-job creation and polling return are front-loaded, and the persona-override caveat is placed where it is relevant. Every clause 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 tool with no annotations and no output schema, this description is quite complete: it covers what the job does, what it returns, and the key routing edge case. The main missing details are the semantics of the `from` parameter and the exact polling endpoint/mechanics, but these are minor against the overall coverage.

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 only 33%, so the description must compensate for undocumented parameters. It does explain `personas` richly—explicit slugs, ordering, router bypass—but `context` gets only an implied role ('routes context to...'), and `from` is not addressed at all. Partial compensation leaves a meaningful gap.

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

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

The description opens with a specific action—'Create an async narada job'—and clarifies the operation by describing the routing flow, persona count, model usage, and return value ('Returns job ID for polling'). This makes the tool's purpose concrete and distinguishes it from result-fetching siblings like fetch_narada_result.

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

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

The description gives actionable guidance about when to pass `personas` versus relying on the router, including an explicit limitation: the router matches keywords only and cannot honor include/exclude requests written in the context. It does not explicitly name alternative tools or state when not to use this one, so it stops short of a 5.

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 behavioral transparency burden. It discloses that a correct answer unlocks and returns the full body, but does not mention side effects, behavior on incorrect answers, persistence of answers, or any authorization requirements. This is a partial disclosure but leaves important behavioral aspects unspecified.

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

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

The description is a single, front-loaded sentence with no redundant information. It efficiently communicates the action and expected result, making optimal use of 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?

For a simple two-parameter tool with no output schema, the description covers the main success path (correct answer returns full body). It stops short of explaining failure behavior (incorrect answer), which is relevant for a submission endpoint. Overall, it is reasonably complete but misses edge-case details.

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

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

Schema description coverage is 0%, so the description must compensate. It frames the operation as submitting an answer to a challenge-gated piece, implying 'slug' refers to the piece identifier and 'answer' is the submitted content. This adds meaning beyond the raw parameter names, though not explicitly structured.

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 identifies the tool's purpose: submitting an answer to a challenge-gated piece. It uses a specific verb ('Submit') and resource ('answer to a challenge-gated piece'), and explains the outcome (correct answer unlocks and returns the full body). This distinguishes it from siblings like fetch_answer 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 provides clear context for when to use the tool—when dealing with challenge-gated content that requires an answer to unlock. It does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to select it appropriately over related tools like fetch_answer.

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 discloses determinism, maximum output counts (8 skill slugs, 5 personas), and that each result includes a 'reason it fired'. It also states 'No LLM classification', which is a meaningful behavioral exclusion. It does not mention side effects or error conditions, but the mapping nature implies read-only behavior.

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

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

The description is two sentences long, with no unnecessary words. The first sentence provides a high-level label, and the second elaborates with concrete details. Every clause adds value, making it highly 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?

The description explains the core function and output shape but lacks an output schema, leaving the exact return format ambiguous. It does not cover edge cases such as empty results, optional parameters, or potential errors. Given the moderate complexity (3 params) and lack of annotations/output schema, this is only partially complete.

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

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

Schema description coverage is 0%, so the description must compensate. It names all three parameters ('files', 'languages', 'git_origin') but provides no additional meaning beyond their existence. There is no format, example, or constraint provided for any parameter, leaving the agent to infer what values are expected.

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 a specific verb ('returns') and resource ('skill slugs and personas'), with explicit inputs ('files + languages + git_origin'). It distinguishes itself from siblings by emphasizing 'No LLM classification', making its non-LLM, rule-based nature clear.

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 through 'Deterministic' and 'No LLM classification', suggesting it is for when a rule-based suggestion is preferred. However, it does not explicitly state when to use this tool versus alternatives, nor does it name any sibling tool for comparison.

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 present, so the description must disclose behavioral traits on its own. It explicitly states that the operation 'replaces' the previous pattern set (destructive), 'writes internal state' (mutation), 'paid' (cost), and 'Owner-only' (authorization). These are meaningful behavioral disclosures beyond the schema. It does not mention failure modes or side effects on other data, but it covers the most critical 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?

The description is extremely concise, with two short sentences that front-load the main action and follow up with the critical constraints. Every word adds value; no fluff or repetition.

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 one-parameter schema and lack of annotations, the description covers the core operation, permissions, and side effects. However, it omits the meaning of the slug parameter and any description of the return value or success criteria, which would be helpful in the absence of an output schema. The description is adequate but has clear 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 input schema contains a single string parameter 'slug' with no description (0% schema coverage). The description does not mention 'slug' at all, leaving its meaning to be inferred from the tool name and the phrase 'a persona's raw journal.' It fails to explicitly state that the slug identifies the persona, which would be necessary for correct invocation.

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

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

The description states a specific verb ('Force-run'), a precise object ('Sonnet synthesis over a persona's raw journal'), and a clear outcome ('replacing the previous pattern set'). This clearly distinguishes it from sibling tools like get_persona_journal or record_persona_reflection.

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?

There is no explicit comparison to alternatives or 'when not to use' guidance. The 'Owner-only — paid + writes internal state' clause provides constraints (authorization, cost, mutability), and 'Force-run' implies a manual override, but it never explains the typical use case vs other persona tools. The usage context is implied rather than 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?

With no annotations, the description discloses the key side effect: 'Writes JSON to content/skills/<slug>.json', and the access requirement. This goes beyond the tool name, though it doesn't detail error behavior or reversibility.

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 waste, and front-loaded with the main purpose. Every word 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 file-writing mutation, it covers the main behavior and auth prerequisite but lacks details on return values, validation, or handling of optional parameters. Given no output schema or annotations, more could be said, but it's 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 description adds meaning only for 'slug' via the file path notation, but leaves 'body', 'title', 'category', and 'tags' unexplained. With 0% schema description coverage, this is a significant gap.

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

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

The description clearly states the verb ('Create or replace'), the resource ('a skill by slug'), and the scope, distinguishing it from sibling tools like delete_skill and get_skill via the upsert semantics.

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

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

It provides clear context that this is owner-only and requires an Authorization Bearer token, implying privileged use. It doesn't explicitly name alternatives, but the purpose statement is clear enough to infer when to use it.

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 responsibility. It does not disclose any behavioral traits such as whether the operation is read-only, what happens on signature mismatch, return format, or potential errors. The read-only nature is only implied by 'verify'.

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

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

The description is a single, well-structured sentence with no redundant information. It conveys the essential purpose without any 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?

The tool is simple (one parameter, no output schema), so the description is minimally adequate. However, it could be more complete by stating the return value (e.g., boolean) or failure behavior, especially since no annotations provide 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 description coverage is 0% and the description does not explicitly explain the 'slug' parameter. The phrase 'a piece' vaguely suggests slug identifies the content, but it does not clarify the parameter's format, role, or relationship to the signature.

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 a specific action: 'Verify a piece's Ed25519 signature against the server's owner public key.' The verb 'verify' and resource 'signature' are unambiguous, and it distinguishes itself from siblings by its unique cryptographic verification 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 provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, typical scenarios, or when not to use it, leaving the agent to infer usage solely from purpose.

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