TomeVault

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

Annotations already declare readOnlyHint=true, indicating no state modification. The description uses 'convert' which is consistent but does not add behavioral context beyond what annotations provide. No contradictions.

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

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

Two sentences with no wasted words. The first sentence front-loads the action and formats, the second reinforces the purpose. Optimal length for clarity.

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 straightforward conversion tool with 4 parameters and no output schema, the description covers the core behavior. Lacks mention of output format or error handling, but schema details (max lengths, enum) compensate. Nearly 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 100% for all 4 parameters. The description does not add meaning beyond what the schema already provides for each parameter, so baseline score of 3 applies.

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

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

The description clearly states the verb 'convert' and the resource 'pasted instruction-file text' and lists specific target formats (claude_md, agents_md, etc.). It differentiates from sibling tools which deal with retrieval or scanning, not transformation.

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 for converting instruction text to other tool formats but provides no explicit guidance on when to use this tool versus alternatives or when not to use it. No exclusions or prerequisites are mentioned.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds value by detailing the exact fields returned (quality grade, security scan, decay risk, etc.), providing context beyond safety annotations.

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

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

Single, moderately long sentence that lists all returned fields. Front-loaded with purpose, but the density of information is appropriate. 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 3 parameters and no output schema, the description adequately specifies what is returned. However, it could mention the relationship to sibling tools (e.g., 'for a tome identified by owner/repo/skill_path'). Sufficient for a read-only 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?

Input schema coverage is 100%, so baseline is 3. The description does not add extra meaning about parameters; it focuses on the output. No contradiction or additional semantics 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 that the tool returns the signed attestation record for a tome, listing specific fields it contains. This distinguishes it from siblings like get_tome (returns full content) and verify_attestation (verifies attestation).

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

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

No guidance on when to use this tool versus alternatives such as get_tome or verify_attestation. The description does not mention scenarios or 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?

Annotations already declare readOnlyHint and openWorldHint. The description adds value by specifying that every response includes provenance verdicts (quality grade, security scan, decay risk) and the content hash. No contradictions with annotations.

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

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

Two sentences, each packing essential information: the primary action and the key response detail. No fluff, front-loaded with 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?

Given the parameter count and schema coverage, the description adequately covers the tool's usage. It mentions response contents but does not detail error cases or authentication requirements. Still, it is mostly complete for a fetch operation with provenance.

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

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

Schema coverage is 100%, and the description essentially repeats schema descriptions for owner, repo, format, and skill_path. It adds no new semantic information beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Fetch' and the resource 'one tome's content', specifies the default format, and mentions the provenance information included in the response. This distinguishes it from siblings like search_tomes and get_provenance.

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 for fetching content with provenance, but it does not explicitly state when to use it versus alternatives such as get_provenance alone. The 'default claude_md' hint is useful but no guidance on when to omit format or use skill_path.

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?

Beyond annotations (readOnlyHint, openWorldHint), the description adds scope requirements, encryption behavior, and indistinguishable not-found error, offering substantial behavioral context.

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

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

Two sentences cover purpose and important behavioral notes. Concisely front-loaded with 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?

Given the simple read operation, no output schema, and rich annotations, the description adequately covers scope, encryption, and error behavior.

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

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

Schema covers the single parameter with a description. The tool description adds context about content and encryption but does not enhance parameter understanding beyond schema.

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

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

The description clearly states the tool fetches a vault item by ID with its content. However, it does not explicitly differentiate from sibling tools like list_vault_items or search_tomes.

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

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

The description mentions required scope and encryption behavior but provides no guidance on when to use this tool versus alternatives, leaving usage 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?

Annotations already indicate readOnlyHint and openWorldHint; the description adds useful behavioral context: required scope ('items:read') and the fact that encrypted items are never listed, which is not covered by annotations.

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

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

Three concise sentences with no filler, front-loaded with the core purpose, then adding requirements and caveats. Every sentence adds value.

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

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

Given the simple single-parameter schema and presence of annotations, the description covers token scope and exclusion but omits details about pagination, response format, or total count, leaving some gaps for a list tool.

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

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

Schema description coverage is 0% for the single 'limit' parameter, and the description does not mention the parameter at all, failing to add meaning beyond the schema's basic constraints.

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

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

The description clearly states the verb 'List' and the resource 'items in your TomeVault', adding scope constraints ('that this token can read') and distinguishing from siblings like get_vault_item by emphasizing listing vs. single item 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 mentions required scope and exclusion of encrypted items but does not explicitly guide when to use this tool vs. alternatives like get_vault_item or search_tomes, leaving context implicit.

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?

Annotations provide readOnlyHint=true, but description adds crucial context: text is scanned and discarded, never stored, and consistency findings are predictions. This goes beyond annotations.

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

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

Description is concise, front-loaded with purpose, and each sentence adds value. No unnecessary words.

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

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

Tool has 2 parameters, no output schema, and annotations present. Description covers purpose, usage context, behavioral transparency, and parameter meaning, making it complete for agent decision-making.

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

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

Schema has 100% coverage for both parameters. Description adds minimal extra meaning beyond what schema already provides (e.g., 'instruction-file text'). Baseline of 3 is appropriate.

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

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

Description clearly states the tool scans instruction-file text for safety, clarity, loadability, and cross-model consistency, returning a verdict. It distinguishes itself from sibling tools like convert_content and get_provenance.

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

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

Explicitly says 'Use before loading a third-party file' and warns that consistency findings are predictions. However, it does not specify when not to use or mention 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?

Beyond annotations (readOnlyHint, openWorldHint), description adds that the tool returns ranked matches with specific fields and explicitly states it does not return file contents, which is critical 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?

Two sentences with no wasted words. First sentence conveys core purpose, second clarifies return value and limitations. Front-loaded and efficient.

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

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

With 5 parameters, no output schema, and rich annotations, the description covers purpose, return fields, and what to exclude. Could mention ranking or pagination, but adequate for agent usage.

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

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

Schema coverage is 80%, so baseline is 3. Description does not add per-parameter semantics beyond what the schema provides (e.g., enum descriptions are in schema). Description mentions filtering by format, kind, grade, but schema already captures that.

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

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

Description states specific verb 'Search', resource 'TomeVault for agent context files (tomes, configs, skills)', and action context 'by a task description'. It also clarifies return value and excludes file contents, distinguishing it from similar tools like get_tome which likely returns full 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?

Clearly indicates usage when searching for context files via task description, implying it is the search tool among siblings. Does not explicitly state when not to use or name alternatives, but the sibling list provides 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?

The description discloses critical behavioral traits beyond the 'readOnlyHint' annotation: it confirms that no submitted data is stored ('Nothing submitted is stored'), and explains that the returned verdict contains a prediction, not a verified fact. This provides transparency about the tool's limitations and data handling.

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

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

The description is three sentences long, front-loading the core function in the first sentence. Every sentence adds essential information: what the tool does, what it confirms, and key caveats about behavior and data handling. 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?

Given the tool's complexity (two parameters, no output schema), the description adequately covers input, verification steps, and output nature (signed verdict with prediction note). It could be more complete by specifying the verdict's format or fields, but the existing info is sufficient for an agent to use the tool correctly.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by explaining the purpose of the 'content' parameter ('the instruction file the attestation signs') and clarifying the relationship between 'attestation' and 'content'. It goes beyond the schema by describing the verification process.

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 verify a TomeVault attestation document, including signature authentication and optional file integrity check. It uses a specific verb ('verify') and resource ('attestation document'), and distinguishes from sibling tools like 'get_provenance' or 'scan_content' by focusing solely on attestation verification.

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 the tool (to verify attestations) but does not explicitly state when not to use it or suggest alternatives among siblings. No exclusions or comparative guidance are provided, leaving the agent to infer usage context.

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