PAIDEIA MCP

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

No annotations provided; description uses 'Return' implying read-only, but does not explicitly state nondestructive nature or potential side effects. Adequate but not explicit.

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

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

Single sentence that efficiently conveys purpose and content. Front-loaded with main action. Could benefit from slight restructuring for clarity, but 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?

No output schema, so description should hint at return format. Mentions 'machine-readable' but not specific (JSON, etc.). Parameters explained in schema, but overall lacks detail on what the manifest looks like. Adequate for a simple retrieval 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 covers both parameters with descriptions (100% coverage). Description adds no extra parameter-level details beyond what schema provides. 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?

Description clearly states it returns 'Alt manifest' with specific contents (setup, SDK boundary, PAIDEIA rules, action-to-tool recipes). Distinguishes from siblings like list_paideia_actions by being comprehensive, but could be clearer on how it differs.

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 vs alternatives like list_paideia_actions or alt_workflow_guide. Missing criteria for selection among similar sibling tools.

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

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

No annotations are provided, so the description carries the full burden. It only states what the tool returns, with no disclosure of side effects, prerequisites, or limitations. For a tool that likely performs a safe read operation, the description does not confirm this or provide any behavioral context.

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

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

The description is a single, well-structured sentence that directly communicates the tool's purpose. There is no extraneous information, making it highly efficient for an AI agent to parse.

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 returns static setup instructions and has no output schema, the description covers the core functionality. However, it could be more complete by including an example or noting that the values are specific to a local stdio MCP server, which would further aid the agent.

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?

Although the schema has 50% description coverage (two parameters have descriptions), the tool's description does not add any meaning to the parameters. It only describes the return values, leaving the agent to rely solely on the schema for parameter usage. The description adds no value beyond the existing schema documentation.

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

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

The description clearly states 'Return exact field-by-field values for Alt's local (stdio) MCP server form', specifying a concrete verb ('return'), a specific resource ('Alt's local MCP server form'), and lists the fields involved. This distinguishes the tool from siblings like 'alt_capability_manifest' and 'alt_workflow_guide'.

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 setup instructions are needed but provides no explicit guidance on when to use versus alternatives, nor does it mention when not to use the tool. The context of the sibling tools suggests it is specialized, but the description lacks definitive usage boundaries.

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 bears full responsibility for behavioral disclosure. It does not state whether the tool has side effects, requires authentication, or any other behavioral traits. It only says it returns a guide, implying a read operation, but this is not explicit.

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 states the core purpose, and the second provides context. Ideal 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?

The description is too brief given no annotations or output schema. It does not describe the return format, error handling, or typical usage scenarios. For a tool returning a guide, more detail on content and structure is warranted.

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 'project_root' has a description. The description does not explain the 'scenario' parameter or its enum values. The tool description adds no additional meaning beyond what the schema already provides.

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

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

The description clearly states it returns an 'Alt-local-model PAIDEIA operating guide' and explains its purpose as mirroring MCP prompts for clients that only expose tools. The verb 'Return' and resource 'operating guide' are specific, but it could be more precise about what the guide contains.

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 explicit guidance on when to use this tool vs. siblings like 'list_paideia_actions' or 'paideia_doctor'. The mention of 'clients that only expose tools' gives some context but isn't sufficient for distinguishing use cases.

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

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

No annotations provided, so the description must disclose behavior. It only states the action (append) but does not explain what happens if the file doesn't exist, if entries are deduplicated, or any side effects. The project_root parameter description helps but is insufficient for full 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 a single, efficient sentence with no extraneous words. It is front-loaded with the core action.

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

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

For a simple append tool, the description is minimal but adequate. However, it lacks details on output or error handling. With no output schema and no annotations, more context would be beneficial, though not strictly necessary.

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 29% (2 of 7 parameters described). The description adds no additional parameter details beyond what the schema provides, such as the meaning of error_type enum values or the format of source/date.

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 'append' and a specific resource 'canonical YAML error entry to errors/log.md'. It clearly distinguishes from sibling tools like write_artifact which are more general file 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?

No guidance on when to use this tool versus alternatives. It does not mention any prerequisites or exclusions, 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.

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

With no annotations, the description carries the full burden but only mentions the basic action. It does not disclose behaviors like folder overwrite, git initialization, error handling, or what happens if notes already exist. Parameters like 'overwrite_notes' and 'continue_on_error' are not referenced.

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

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

The description is a single, efficient sentence that gets to the point. It could be slightly expanded to include important caveats, but it is not verbose.

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 12 parameters, 3 required, and no output schema, the description is severely incomplete. It does not explain parameter purposes, return values, or provide context for when to use this complex composite tool.

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

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

Schema description coverage is only 17%, and the tool description adds no parameter explanations. Most parameters lack descriptions in both the schema and the description, leaving the agent to guess their meaning.

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 creates a PAIDEIA course folder and imports Alt note transcripts in one call. It effectively distinguishes from sibling tools like 'init_course' and 'import_alt_notes' by combining both actions.

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 using 'init_course' and 'import_alt_notes' separately. There are no when-not-to-use tips or alternative suggestions.

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 bear the full burden of disclosing behavioral traits. It only says 'write a draft' without specifying if it overwrites existing files, whether it requires network access, or any side effects. The 'force' parameter hints at regeneration, but the description does not clarify the overall 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 extremely concise with a single sentence, which is efficient. However, it sacrifices clarity due to possible typos and lack of structure, making it somewhat cryptic for a tool with three parameters and no annotations.

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 writes files (a significant action) and has no output schema or annotations, the description is insufficient. It does not explain the format or content of the generated files, any required filesystem state, or error conditions, leaving the agent with incomplete 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 100%, so the baseline is 3. The description adds no extra meaning beyond the schema's parameter descriptions; it does not elaborate on 'weak_zones' or 'project_root' behavior. Hence, it neither improves nor worsens understanding.

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 it inventories converted markdown files and writes draft index files, giving a verb and resource. However, the phrasing 'converted/ markdown files' is unclear (likely a typo), and it does not clearly distinguish from sibling 'save_course_index' which might perform a similar but distinct action.

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

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

No guidance is provided on when to use this tool versus alternatives like 'save_course_index' or other siblings. The description does not mention prerequisites, use cases, or exclusions, leaving the agent to infer 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?

No annotations are provided, so the description must carry full behavioral transparency. It accurately describes a read operation ('return') without side effects, which aligns with the read-only nature. However, it does not mention error handling or behavior when artifacts are 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 a single, well-structured sentence that front-loads the key outputs. Every word serves a purpose; there is no superfluous content.

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 simplicity (one optional param, no nested objects) and no output schema, the description is largely complete. It lists all returned fields, though it does not specify the return format (e.g., single object vs. array), which might be inferred from the singular 'phase'.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add any parameter information beyond what the schema already provides. The schema itself already contains a detailed explanation for 'project_root'.

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 specific artifact-derived data: course phase, days_until_exam, and top_miss_pattern, with an explicit list of possible phases. This distinguishes it from sibling tools that handle ingestion, artifact listing, or course initialization.

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 users need phase analysis, but does not explicitly state when to use this versus alternatives like 'list_artifacts' or 'init_course'. The parameter hint about setting 'project_root' provides some context, but no when-not-to-use guidance.

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

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

No annotations are provided, so the description carries the full burden. It mentions reading 'errors/log.md' and generating a weakmap but does not disclose side effects, prerequisites (e.g., file existence), output format, or whether it modifies any state.

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

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

Single sentence is concise and front-loaded with the action. However, it omits critical information, which reduces its effectiveness.

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 output schema and no annotations, the one-sentence description is insufficient. It lacks explanation of the output, file prerequisites, and how parameters affect behavior, leaving the agent underinformed.

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 does not mention either parameter. However, the input schema already provides descriptions for both 'project_root' and 'concept' (50% coverage, but both documented), so the description adds no extra meaning. 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?

Description clearly states the action 'Generate a compact timestamped weakmap' and the source 'errors/log.md', but 'weakmap' is a domain-specific term not explained, which may confuse an AI agent without context. Sibling tools like hwmap suggest similar functionality, but no differentiation is provided.

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 like hwmap or other map-generating tools. Context signals and sibling names do not clarify usage scenarios.

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

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

No annotations are provided, so the description must carry the full burden. It mentions the output path and confidence tier, but does not disclose side effects such as file overwriting, permissions required, or error behavior. This is insufficient for a tool that writes files.

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?

A single sentence conveys the core purpose without any wasted words. It is front-loaded with the essential action and result.

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 output location and that it includes a confidence tier, but lacks details on return values (no output schema), error handling, or idempotency. Given the tool writes a file, more context on side effects and success criteria would improve completeness.

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

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

Schema coverage is 100%, so each parameter is already documented. The description adds context about the output file pattern and confidence tier, but does not provide additional parameter-specific meaning beyond what the schema offers. 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?

The description clearly states the action ('OCR'), the resource ('single hand-written answer PDF'), and the output ('into answers/converted/<stem>.md with a confidence tier'). It is specific and distinguishes from siblings like ingest_pdfs which likely handles multiple PDFs.

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 a single PDF, but does not explicitly state when to use this tool vs alternatives (e.g., ingest_pdfs for batch processing). No guidance on prerequisites 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?

No annotations are provided, so the description must fully describe behavior. It implies read-only operation but does not disclose any side effects, permissions, or reliability. Critical behavioral traits are 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?

Single sentence, no redundant phrases. Every word earns its place; the description is as concise as possible.

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 should elaborate on what 'HW-density exam-priority rows' means and the output format. It covers the core action but lacks detail about the return value.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add extra meaning beyond the schema's parameter descriptions; it simply mentions the parameter names in passing.

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

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

The description clearly states the tool reads a specific file ('course-index/coverage.md') and returns a specific output ('HW-density exam-priority rows'). This distinguishes it from sibling tools like build_course_index or generate_weakmap.

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 does not mention prerequisites, context, 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?

With no annotations, the description must disclose behavioral traits. It states 'Import' but does not mention side effects (filesystem changes), permissions required, idempotency, or behavior when overwrite is false/true. The optional conversion is noted but not conditioned.

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 (35 words) that front-loads the action and destination. It is appropriate in length but could be more structured with bullet points or conditional notes.

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 (9 parameters, no output schema, low schema coverage), the description is incomplete. It omits return values, error handling, parameter interactions (e.g., overwrite, write_converted), and prerequisites like project_root. A comprehensive description is needed.

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 22%. The tool description adds no parameter details, leaving 78% of parameters (e.g., title, transcript, memo, summary, write_converted, overwrite) semantically empty. It fails to compensate for the sparse schema.

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

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

The description clearly states the action (Import), resource (Alt active note/transcript), destination (materials/<category> and optionally converted/<category>), and purpose (PAIDEIA analysis). It is specific and distinguishes from siblings like import_exam_radar, though not explicitly from the plural import_alt_notes.

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 vs alternatives (e.g., import_alt_notes for bulk import). It lacks prerequisites, context, or exclusions, leaving the agent to infer usage from the name alone.

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

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

No annotations exist, so the description carries full burden. It mentions importing into two directories but does not disclose behaviors like overwrite, error handling, or write_converted. Key behavioral traits are 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?

A single, front-loaded sentence that directly states what the tool does. No wasted words; efficient and clear.

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 concise purpose, the description is incomplete for a tool with 6 parameters and no output schema. It lacks explanation of parameter interactions, default behaviors, and overall workflow. Schema descriptions partially fill the gap but the description should tie them together.

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 only 17% schema description coverage, the description adds some value by specifying source and destination paths, but it does not compensate for the many undocumented parameter semantics (e.g., overwrite, continue_on_error, write_converted).

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 batch-imports Alt notes from a specific source (alt.notes.getContent) into two specific target directories (materials/<category> and converted/<category>). This distinguishes it from the singular sibling import_alt_note.

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 batch usage but does not explicitly state when to use this tool versus alternatives like import_alt_note. No usage context or exclusions are provided.

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

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

No annotations are provided, and the description lacks details about side effects, overwrite behavior, required permissions, or failure modes. For a tool that writes files, such transparency is essential but 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 a single sentence, which is concise. However, it is so brief that it omits important context, making it borderline under-specified.

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, no annotations, and low parameter coverage, the description is incomplete. It does not specify input formats, output behavior, or what 'gold-zone weakmap' implies.

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% (only project_root has a description). The description does not explain any parameter, leaving export_md and course_name undefined. It adds no value beyond parameter names.

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 ('Import') and the specific output files ('radar.md, coverage.md annotation, and a gold-zone weakmap'). It differentiates from sibling tools like parse_exam_radar_export (which parses without importing) and generate_weakmap (which may generate from other sources).

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. Sibling tools like parse_exam_radar_export and generate_weakmap exist, but the description does not explain prerequisites, ordering, or selection criteria.

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 idempotency (unless force=True), the OCR engine with fallback behavior, and the effect of project_root. Since no annotations exist, it carries full burden; it covers key behavioral aspects well.

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—a single sentence plus a brief note on idempotency. No wasted words; front-loaded with essential purpose information.

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

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

Given no output schema and no annotations, the description covers core functionality, parameters, and behavior. It lacks explicit mention of output location but the force parameter schema hints at it. Overall sufficient for the tool's complexity.

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

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

Schema coverage is 100% and the description adds meaningful context: it explains engine fallback logic, default project_root behavior, and how categories restrict subfolders. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: converting all PDFs in materials/**/*.pdf to markdown via an OCR engine. It specifies the action (render), the resource (PDFs), and differentiates from siblings like grade_pdf by focusing on ingestion.

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 batch PDF conversion but does not explicitly state when to use this tool vs alternatives like grade_pdf or other siblings. No guidance on prerequisites or exclusions is provided.

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

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

No annotations are provided, so the description must disclose behavioral traits. It only says 'create... folder skeleton' but does not explain side effects, required permissions, or whether it overwrites existing data.

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 short sentence, front-loaded. It is concise but at the expense of completeness; it could include more details without being verbose.

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 7 parameters, low schema coverage, no output schema, and no annotations, the description is severely incomplete. An agent cannot determine how to correctly invoke this 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?

With only 29% schema coverage, the description should add meaning to the 7 parameters. It does not mention any parameters or their roles, failing to compensate for the schema gaps.

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 'Create a PAIDEIA local course folder skeleton' – a specific verb and resource. However, it does not differentiate from similar sibling tools like bootstrap_alt_course, which likely also creates course structures.

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 bootstrap_alt_course. No context on prerequisites or when to avoid 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 only states 'List markdown artifacts', implying a read-only operation, but fails to disclose any side effects, permissions, system interactions, or limitations.

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?

A single, clear sentence that front-loads the main action and resource. No unnecessary words 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 simplicity of the tool (2 optional params, no output schema) and lack of annotations, the description is minimally adequate but lacks details on return format, artifact nature, or relation to sibling tools.

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 does not add meaning beyond the input schema. The glob_pattern parameter (50% coverage) is not explained in the description; only project_root is mentioned, and its description adds no new information.

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 'markdown artifacts', and specifies the context 'PAIDEIA course folder'. It effectively distinguishes from sibling tools like read_artifact and write_artifact.

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 read_artifact or write_artifact. The description only implies its use for listing, but does not provide context 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?

With no annotations, the description carries full burden for behavioral information. It only states the action (list) but does not disclose whether it is read-only, what side effects exist, or what happens if the repo_root is not found. No details about return format or pagination.

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 of 12 words. It efficiently conveys the primary purpose without redundancy, though it could include additional useful context without sacrificing 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?

Given no output schema, the description should explain the return value (list of action names, details, etc.) but does not. Also, with many sibling tools, more context on when to use this tool is needed. The description feels incomplete for a list action.

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 does not add any meaning beyond the input schema, which already covers the single optional parameter with a description. Since schema coverage is 100%, the baseline is 3, and the description does not improve upon it.

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

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

The description clearly states that the tool lists PAIDEIA actions with the specific context 'available to Alt's local model'. This distinguishes it from other sibling tools that might list or manipulate actions in different contexts, though it doesn't fully differentiate from similar list tools like 'prepare_paideia_action'.

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

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

No guidance is provided on when to use this tool versus alternatives such as 'prepare_paideia_action' or 'paideia_doctor'. The description lacks any when-to-use or when-not-to-use instructions.

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 convey behavioral traits. It describes the return value but does not explicitly state that the operation is read-only or non-destructive. However, the content implied (returning a manifest) suggests no side effects, earning a mid-range score.

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 earning its place: the first explains the alias purpose, the second details the output. Front-loaded with critical naming guidance, no redundant or vague 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?

Despite no output schema, the description fully enumerates the return content (setup, SDK boundary, rules, recipes). The two optional parameters are thoroughly explained with default behaviors, and the tool's purpose is self-contained.

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 adds valuable default-behavior details for both parameters (auto-discovery for repo_root, CWD default for project_root). This goes beyond the schema's type and description, aiding 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 clearly states that this tool returns the machine-readable Alt manifest, specifically naming its components (setup, SDK boundary, PAIDEIA rules, action-to-tool recipes). It also distinguishes itself as the PAIDEIA namespace alias for alt_capability_manifest, clarifying its unique identity among siblings.

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

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

The description explicitly advises to use this exact name when Alt searches for it, providing clear context for when to invoke this tool. While it does not list when-not-to-use or alternatives, the specificity is sufficient given the large sibling set.

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 bears full burden. It mentions returning values, but does not disclose if it is read-only, whether it requires authentication, or any side effects. Lacks detail on behavior beyond the output format.

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, but the phrasing is awkward and redundant. It would benefit from clearer structure and more precise language.

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

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

Given 4 parameters and no output schema, the description is insufficient. It does not explain what the tool returns in full, nor does it provide enough context for proper 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?

The description does not mention any parameters, so it adds no meaning beyond the schema. Schema coverage is 50%, and the description fails to compensate for undocumented 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 states it is an alias and should return setup instructions, but does not clearly define what the tool does. It mentions 'return exact field-by-field values', which is vague and does not convey a specific action or outcome.

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 advises to use this exact name when Alt searches for it, but provides no guidance on when to use this tool versus alternatives (e.g., the base alt_setup_instructions). No exclusions or context for 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?

No annotations are provided. The description mentions it returns an operating guide but does not disclose side effects, authentication needs, rate limits, or what the output contains. Limited behavioral context beyond the purpose.

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, each adding value: namespace alias, usage instruction, and purpose. 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?

With 2 params, no output schema, and an enum with 10 options, the description covers the basics but omits elaboration on scenario values and project_root behavior. Adequate but not thorough.

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%; scenario lacks description but has enum, project_root has description. The tool description adds no extra parameter meaning beyond the schema, so baseline score 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 it is a PAIDEIA namespace alias for alt_workflow_guide, specifies when to use the exact name, and explains it returns an operating guide. This distinguishes it from siblings like alt_workflow_guide.

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 to use this name when Alt searches for PAIDEIA__alt_workflow_guide and notes it mirrors MCP prompts for clients exposing only tools. Lacks explicit when-not statements but provides sufficient 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?

No annotations are provided, and the description only states the action and file location. It does not mention side effects, permissions, error handling, or whether the file is created if missing. The behavioral disclosure is minimal.

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 but includes a repetitive alias statement. It is adequately structured but could be more efficient by combining the alias and action into one sentence.

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 7 parameters, no output schema, and no annotations, the description is too terse. It omits details like YAML format, required fields, and the relationship to sibling 'append_error', leaving the agent underinformed.

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 no information about the parameters. Only 29% of schema properties have descriptions, and the tool description fails to clarify the meaning or usage of the many parameters (e.g., problem_id, summary, error_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 clearly states the action 'Append one canonical YAML error entry to errors/log.md', specifying the verb and resource. However, it does not differentiate this tool from its sibling 'append_error', which may be identical.

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 only usage hint is 'Use this exact name when Alt searches for PAIDEIA__append_error', which addresses naming rather than when to use the tool versus alternatives. No context on when to append errors or when not to.

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 must fully disclose behavioral traits. It does not mention whether the operation is destructive, requires specific permissions, or has side effects (e.g., git initialization implied by the git_init parameter). The description is too minimal to inform the agent about consequences of invocation.

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

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

Two sentences with no redundancy. Every word serves a purpose: identifying the alias, specifying when to use it, and stating the core action. This is an exemplary level of conciseness for a tool description.

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 complexity (12 parameters, nested input objects, no output schema), the description covers only the top-level action. It lacks explanation of parameters, return values, behavioral details, and how this tool fits into the broader workflow of PAIDEIA tools. The description is insufficient for the agent to use the tool correctly without additional 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 only 17%, yet the description adds little parameter-level meaning beyond stating the high-level action. It does not explain critical parameters like notes, overwrite_notes, continue_on_error, or git_init. The schema provides some defaults and types, but the description fails to compensate for the low coverage.

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

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

The description explicitly states the tool's purpose: 'Create a PAIDEIA course folder and import an initial batch of Alt note transcripts in one call.' This is a specific verb+resource combination that clearly differentiates the tool's core function from potential confusion with sibling tools like bootstrap_alt_course.

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 advises to 'Use this exact name when Alt searches for PAIDEIA__bootstrap_alt_course,' providing some context for when to invoke this alias. However, it offers no guidance on when not to use it or how it differs from the non-prefixed sibling bootstrap_alt_course, leaving the agent with incomplete decision-making information.

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, and the description does not disclose behavioral traits such as side effects (e.g., file creation or modification), permissions required, or whether it is safe or destructive. The description only states what the tool does, not how it behaves beyond the 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 concise with two sentences: one establishing the alias and usage, the other describing the action. It is front-loaded and avoids unnecessary words, though it could be slightly more structured.

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

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

Given the tool's simplicity and that the schema covers parameters, the description provides the core information about its purpose and output files. However, it lacks details about return values or error states, and since there is no output schema, the description does not fully compensate. It is adequate but not 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 already describes all three parameters (force, weak_zones, project_root) with clear descriptions. The tool description adds no additional meaning or context about the parameters beyond what is in the schema, but since schema coverage is 100%, the 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?

The description clearly states the tool is a PAIDEIA namespace alias for build_course_index and describes the action: 'Inventory converted/markdown files and write a draft course-index/{summary,patterns,coverage}.md baseline.' It distinguishes itself from the sibling tool 'build_course_index' by its namespace prefix, making the purpose understandable.

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 advises using this exact name when an AI searches for it, but does not elaborate on when to choose this alias over the non-prefixed sibling or provide context on when not to use it. This gives minimal usage 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 must disclose behavioral traits. It states that the tool 'returns' data, implying a read operation, but does not explicitly confirm safety or side effects. It also does not mention authentication requirements, rate limits, or any destructive potential. The disclosure is partial.

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 consists of two concise sentences that convey identity, usage, and return value without unnecessary words. It is well-structured and 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?

The description explains what the tool returns and that it derives data from artifacts. However, it does not clarify the relationship with the sibling 'course_phase' (whether they are identical or have differences), nor does it specify prerequisites or error conditions. Given the simple tool signature, it 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 input schema has 100% coverage for the single parameter (project_root) with a clear description in the schema. The tool description adds no additional information about the parameter beyond what the schema already provides. With high schema coverage, the description is not required to add much, but it contributes nothing.

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 is an alias for course_phase and specifies the return values: course phase, days_until_exam, top_miss_pattern. However, it does not differentiate how this alias differs from its sibling tool 'course_phase', which could lead to confusion about when to use which.

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 usage instruction: 'Use this exact name when Alt searches for PAIDEIA__course_phase.' This provides context for invocation but lacks guidance on when not to use this tool or how it compares to the non-aliased sibling. No alternatives or exclusions are mentioned.

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

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

No annotations are provided, so the description carries full burden. It describes a diagnostic operation, implying read-only behavior, but does not confirm lack of side effects or state whether external dependencies are checked without modification.

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 that is reasonably concise, though it lists many aspects. It could be slightly tighter but is not overly verbose.

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

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

No output schema is provided, and the description does not explain what the tool returns (e.g., a report, status codes, or errors). For a diagnostic tool, this is a significant 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?

Schema coverage is 100%, so the schema already documents both parameters with descriptions. The tool description does not add additional meaning beyond what is in the schema, meeting the baseline.

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

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

The description uses the specific verb 'Diagnose' and clearly lists the resources: install health, dependencies, readiness, prerequisites, next steps. It distinguishes itself from sibling tools that perform actions like init_course or build_course_index.

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 does not provide any guidance on when to use this tool versus alternatives. No explicit context such as 'use this before starting a course' or 'when troubleshooting issues' is given.

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

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

No annotations are provided, so the description carries the full burden. It only says 'Generate a compact timestamped weakmap from errors/log.md', implying a read operation from a specific file, but no details on side effects, file modifications, errors, or the nature of the weakmap. For a tool that generates output, behavioral details are lacking.

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 has three sentences, but the first two are meta-instructions about namespace aliasing, which could be omitted or placed elsewhere. The core functional description is only one sentence. While not overly long, it is not optimally concise due to the extraneous meta information.

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

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

Given the tool has 2 parameters, no output schema, and no annotations, the description is incomplete. It does not explain what a weakmap is, how the 'concept' parameter is used, or what the output format looks like. The distinction from the sibling 'generate_weakmap' is not clarified. The description leaves significant gaps for an agent to correctly invoke the 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 has 2 parameters: 'concept' (no description) and 'project_root' (with description). Schema coverage is 50%. The description does not add any extra meaning to the parameters; it fails to explain what 'concept' does or how to use it. The 'project_root' description in the schema is adequate, but the tool description adds no 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 'Generate a compact timestamped weakmap from errors/log.md', which is a specific verb and resource. However, the first two sentences are meta-instructions about the namespace alias, cluttering the purpose. The actual purpose is clear but not front-loaded.

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 does not explicitly state when to use this tool versus alternatives. There is a sibling tool 'generate_weakmap' without the PAIDEIA prefix, but no guidance on when to choose one over the other. The instruction 'Use this exact name when Alt searches...' is about naming, not usage 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?

No annotations are provided, so the description carries the full burden. It clearly states the tool's behavior: OCRs a PDF to a specific path with a confidence tier. However, it does not disclose potential side effects or failure modes.

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

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

The description is concise (44 words across two sentences), front-loaded with the alias info, and the functional statement is direct and clear.

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 the description mentions a 'confidence tier' but does not specify the return value or format. This leaves some ambiguity about what the agent should expect after 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?

The input schema already has 100% parameter descriptions. The description adds no new parameter details beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states that this tool OCRs a single hand-written answer PDF into a specific markdown file with a confidence tier. It also distinguishes itself as a namespace alias for grade_pdf.

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 as an alias when 'Alt searches' for this tool, but it does not provide explicit when-to-use or when-not-to-use guidance, nor does it reference alternatives beyond the sibling grade_pdf.

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 exist, so the description bears full responsibility. It states the tool reads a file and returns data, implying a read-only, non-destructive operation. However, it omits details like permissions, error handling, or what happens if the file is missing, leaving 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 with no extraneous information. The first sentence identifies the alias and usage, the second defines the action. Every word serves a purpose, making it efficiently scannable.

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 is simple (2 optional params, no output schema), the description covers the core function. However, it lacks details on return format, relationship to sibling 'hwmap', and error scenarios, leaving questions for an agent trying to invoke 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 100%, with both parameters ('mode', 'project_root') described in the schema. The tool description adds no additional meaning or context to these parameters beyond what the schema provides, so baseline score 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 tool reads 'course-index/coverage.md' and returns 'HW-density exam-priority rows', with a specific verb and resource. It distinguishes itself from sibling 'hwmap' by being the PAIDEIA namespace alias, making its purpose unmistakable.

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 only advises to use this exact name when Alt searches for it, but does not provide when-to-use vs. alternatives. Siblings include both 'hwmap' and this alias, yet no guidance is given on choosing between them, limiting practical utility.

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 fully disclose behavior. It mentions importing into two directories (materials and converted), but omits details about file overwrites, error conditions, permissions, or side effects. The tool writes files, yet behavior beyond the destination is opaque.

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 and front-loads the namespace alias explanation. It is concise, though the first sentence is somewhat redundant given the tool name itself.

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 9 parameters, no output schema, and low schema coverage. The description only covers the high-level purpose and destination, missing essential context about required inputs, parameter effects, and return values. It is inadequate for safe and 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 only 22% (2 of 9 parameters described). The description does not mention any parameter beyond implying 'category' from the path. Required parameters like 'title' and 'transcript' are not explained, nor are defaults or the meaning of 'overwrite' and 'write_converted'.

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 imports an Alt active note/transcript into materials/<category> and optionally converted/<category> for PAIDEIA analysis. However, it does not differentiate this tool from its direct sibling 'import_alt_note' (without the PAIDEIA prefix) or the plural 'import_alt_notes'.

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 minimal guidance: it instructs to use this exact name when Alt searches for the tool, but fails to specify when to use this tool versus the siblings (import_alt_note, import_alt_notes) or any 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 must disclose behavioral traits. It mentions the destination directories (materials/<category> and converted/<category>) but fails to explain side effects, whether the tool is destructive (overwrite parameter exists but not described), error handling, or the return value. The behavioral insight is minimal.

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) but the first sentence is redundant ('alias for import_alt_notes'). It could be more concise by merging. However, it is not overly long.

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

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

Given the tool has 6 parameters, no output schema, and no annotations, the description is incomplete. It does not explain the batch behavior, error handling, output, or the role of each parameter. The tool appears to be a complex batch import, but the description lacks sufficient context for an agent to use it correctly without additional knowledge.

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 17% (only note_id has a description in the schema). The tool description adds no parameter details beyond stating the input comes from 'alt.notes.getContent'. It does not explain the notes array structure or other parameters like overwrite, project_root, or continue_on_error.

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 that the tool batch-imports Alt note payloads into specific directories (materials/<category> and converted/<category>). The verb 'import' and resource 'Alt note payloads' are clear. However, it is ambiguous whether this tool is distinct from the sibling 'import_alt_notes' since it is described as an alias.

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 only usage guidance is to use this exact name when Alt searches for the tool. There is no information about when to use batch vs single import, prerequisites, or alternatives. The sibling 'import_alt_notes' exists but no differentiation is provided.

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

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

No annotations are provided, so the description bears full responsibility. It says the tool imports data into specific files but does not disclose side effects (e.g., overwriting, file creation), required permissions, or whether the operation is destructive. This leaves the agent guessing about critical behavioral traits.

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

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

The description is only three sentences and short, but the first two sentences are repetitive (stating it is an alias and instructing to use the exact name). The core purpose is in the last sentence, which is acceptable but not optimally front-loaded. Some redundancy reduces efficiency.

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 moderate complexity (3 parameters, one required, no output schema), the description is insufficient. It does not explain what 'Exam Radar' is, what format 'export_md' should be in, the role of 'course_name', or what 'gold-zone weakmap' means. The agent lacks enough context 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?

The description makes no mention of any parameters, despite the schema having 3 parameters with only 33% coverage from schema descriptions. The required 'export_md' and optional 'course_name' are entirely unexplained. The description fails to add meaning beyond what the schema already provides.

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

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

The description states it imports Exam Radar into specific files (radar.md, coverage.md annotation, gold-zone weakmap), which is clear about the action and resources. However, it does not differentiate from the sibling tool 'import_exam_radar' other than calling itself an alias, so the distinction is weak.

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 only gives a naming instruction ('Use this exact name...') but provides no guidance on when to use this tool versus alternatives like 'import_exam_radar' or other PAIDEIA tools. There is no statement of context, prerequisites, or exclusion criteria.

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

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

Discloses OCR engine fallback behavior and idempotency. No annotations exist, so description carries full burden. Could mention if original PDFs are preserved, but the info provided is sufficient for non-destructive 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?

Three concise sentences, front-loaded with purpose and namespace alias. No wasted words; each sentence contributes meaningful 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?

Description covers key behaviors and parameters, but lacks explanation of return values or output format. With no output schema, this leaves a gap for the agent to know what to expect from the tool.

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

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

Schema coverage is 100%, but description adds value: it clarifies that idempotency relates to force parameter, and describes engine fallback (qwen3-vl to tesseract). This goes beyond schema descriptions.

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

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

Description states it renders PDFs to markdown via OCR, which is clear verb+resource. It also clarifies it's a namespace alias for ingest_pdfs, but doesn't fully differentiate from that sibling tool.

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

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

Mentions idempotency and that force=True redoes conversion, providing some usage context. However, no explicit when-to-use or comparison to alternatives (e.g., plain ingest_pdfs) is given.

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

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

With no annotations, the description must disclose behavioral traits. It indicates a folder skeleton creation but omits details like potential overwrite behavior, required permissions, side effects, or prerequisites (e.g., existence of project_root). This is insufficient for safe invocation.

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

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

The description is three sentences, but the first two are redundant (namespace alias and instruction to use exact name). The core purpose is stated in the third sentence, but overall it is not as tight as it could be.

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 (7 parameters, no output schema), the description is incomplete. It does not describe what 'folder skeleton' entails, what files are created, what the return value is, or any prerequisites. The agent lacks key context to use the tool effectively.

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

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

Schema description coverage is low (29%), and the description adds no parameter information. It does not clarify meaning or usage of any of the 7 parameters, relying solely on the schema which is sparse. The agent gains no additional guidance from the 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 creates a 'PAIDEIA local course folder skeleton' for Alt or any MCP client, which is a specific verb and resource. It also identifies itself as an alias for init_course, but does not elaborate on differences from sibling tools.

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

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

The description instructs to 'Use this exact name when Alt searches for PAIDEIA__init_course', providing a specific when-to-use hint. However, no when-not-to-use or alternative suggestions are given, and the context for why the alias exists is not explained.

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

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

No annotations are provided, so the description carries full burden. It only states 'List' implying read-only behavior, but does not disclose any other behavioral traits (e.g., auth, rate limits, side effects).

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

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

Three sentences, with the first being redundant (announcing it's an alias). The second is an instruction, the third states the function. Could be more concise but not excessively long.

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 should explain the return format. It only says 'list markdown artifacts' but omits details like whether it returns paths or content. Lacks completeness for 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?

Schema coverage is 50%. The description adds meaning for 'project_root' (absolute path, default CWD) but does not explain 'glob_pattern' beyond its default. Partial but helpful.

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 lists markdown artifacts in a PAIDEIA course folder. It uses a specific verb and resource, but does not distinguish itself from the sibling tool 'list_artifacts'.

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

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

The description includes 'Use this exact name when Alt searches for PAIDEIA__list_artifacts' which provides minimal context for when to invoke it. It lacks when-not-to-use guidance or alternatives.

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

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

No annotations are provided, so the description must carry full behavioral disclosure. It only states it 'lists actions available to Alt's local model' without revealing side effects, permissions, or limitations. This is insufficient for a tool with no annotations.

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

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

Three sentences are concise, with the first two providing necessary context about the namespace alias. While compact, the alias information is somewhat redundant for the main purpose, keeping it from a perfect score.

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 one optional parameter and no output schema. The description fails to explain what 'PAIDEIA actions' are or what the output format looks like, leaving significant gaps for an agent to use 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 description coverage is 100%, with the single parameter 'repo_root' fully described in the input schema. The description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states 'List PAIDEIA actions available to Alt's local model,' providing a specific verb (List) and resource (PAIDEIA actions) with scope. It also distinguishes from the sibling 'list_paideia_actions' by noting this is the PAIDEIA namespace alias.

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 instructs 'Use this exact name when Alt searches for PAIDEIA__list_paideia_actions,' giving clear context for when to use this specific alias. It does not explicitly state when not to use it or mention alternatives, but the context is sufficient.

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

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

Without annotations, the description carries the full burden. It lists diagnostic areas but does not disclose whether the tool is read-only, requires special permissions, or has side effects. Some behavioral context is provided 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 sentences, front-loading the alias and usage note. It is efficient with no redundancy, though the second sentence could be more structured.

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

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

Given no output schema, the description should clarify what the tool returns. It lists diagnostic topics but omits return format or behavior. Also, it doesn't explain the relationship to the non-namespaced alias, leaving contextual 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 description coverage is 100% with rich parameter descriptions. The tool description adds no new semantic information beyond what is already in the input schema, so it meets the baseline for high coverage.

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

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

The description clearly states it diagnoses PAIDEIA MCP install health, dependencies, and readiness, providing a specific verb and resource. However, it doesn't differentiate the purpose from its non-namespaced alias 'paideia_doctor', which is a minor gap.

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 only mentions to use this exact name for Alt searches, which is a naming hint rather than usage context. No guidance is given on when to use this tool over alternatives among the many sibling 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 exist, and the description gives minimal behavioral context—only that it parses a markdown export. There is no disclosure of side effects, required permissions, or output 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 has three sentences, but the first two are mostly redundant (alias and naming instruction). The core action is in the last sentence, but there is minor 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 simple one-parameter tool with no output schema, the description should still indicate the output format or usage context. It only says 'parse,' leaving the agent without enough information to confidently use it.

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

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

The parameter 'export_md' has 0% schema description coverage, and the description does not clarify its semantics (e.g., that it should contain the markdown content). It merely says 'parse a markdown export,' which is too vague.

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 'Parse an OPTIMETA Exam Radar exam-radar:v1 markdown export,' which clearly identifies the verb (parse) and resource (markdown export). However, it does not differentiate from sibling tools like import_exam_radar or parse_exam_radar_export beyond noting the alias.

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 usage guidelines are provided. The description only notes the alias and naming requirement, leaving the agent to infer when to use this tool versus alternatives like import_exam_radar.

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 auto-discovery behavior when repo_root is omitted but fails to mention side effects, permissions, or return values. The core action 'parse into canonical action catalog' lacks detail on what that entails.

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, but the first two are mostly about naming alias and searching, which could be considered redundant. The third sentence is concise. Some waste, but overall acceptable.

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

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

Given the lack of output schema and annotations, the description should provide more context about the outcome of parsing, such as what the 'canonical action catalog' is and whether it returns data or mutates state. The auto-discovery hint is helpful but insufficient.

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

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

Schema description coverage is 100% for the single parameter. The tool description does not add additional meaning beyond what the schema already provides, so the 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 'Parse a PAIDEIA repo into the canonical action catalog,' which specifies the verb, resource, and outcome. However, it does not differentiate from the non-prefixed sibling 'parse_paideia_repo,' so clarity is slightly reduced.

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 only guideline is a naming instruction ('Use this exact name when Alt searches for PAIDEIA__parse_paideia_repo'), which does not help with when to use this tool versus alternatives like the non-prefixed version or other parsing tools.

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

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

No annotations are provided, so the description carries full burden. It only says 'Filter course-index/patterns.md', implying a read operation, but fails to disclose any other behavioral traits such as error handling, rate limits, authorization needs, or side effects.

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

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

The description is very concise with two sentences, no fluff. However, it could be better structured with separate lines for purpose and usage. Still, it 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?

With 3 parameters (none required), no output schema, and low schema coverage, the description should provide comprehensive guidance. It does not explain input parameters, return format, or how to interpret results, making it insufficient 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?

Schema description coverage is only 33% (only project_root has a description). The description hints that 'Pk label or keyword' relates to the query parameter, but does not explain max_chars or project_root. No additional meaning is added over the schema for the other 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?

Clearly states it is a namespace alias for pattern_lookup and that it filters course-index/patterns.md by 'Pk label or keyword'. The purpose is specific and distinguishes it from its sibling pattern_lookup by clarifying its role as an alias.

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?

Only mentions 'Use this exact name when Alt searches for PAIDEIA__pattern_lookup', which is a naming instruction. Does not provide guidance on when to use this tool vs alternatives (e.g., pattern_lookup) or when not 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 bears full responsibility for behavioral disclosure. It hints at composition and preparation but does not describe side effects, return values, or prerequisites. For a tool that likely initiates an action, this lack of transparency is a significant gap.

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

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

The description is short and front-loaded with identity and purpose. The two sentences are efficient with no redundant content. While the first sentence focuses on naming rather than function, the overall structure is acceptable for a concise description.

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 and many sibling tools, the description should explain what the tool returns or accomplishes. It says 'for an Alt local model to execute' but omits the outcome (e.g., does it return an action object? Trigger execution?). This incompleteness reduces usefulness for the agent.

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 60% coverage (some parameters have descriptions). The description adds high-level context ('compose instruction, context, output contract') but does not connect to specific parameters like repo_root or project_root. It does little to clarify parameter meaning beyond what the schema already provides.

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

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

The description clearly states the tool's role as a namespace alias for prepare_paideia_action. It indicates the verb 'compose' and the resource 'PAIDEIA action', specifying it prepares instruction, context, and output contract for execution. However, it doesn't explicitly distinguish from the non-prefixed sibling prepare_paideia_action, leaving ambiguity about when to use each.

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 instructs to 'use this exact name when Alt searches for PAIDEIA__prepare_paideia_action', providing basic usage guidance but no when-to-use or when-not-to-use criteria. It fails to mention alternatives or differentiate from the many similar PAIDEIA__* tools, leaving the agent without clear decision-making 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 must disclose behavioral traits but only states the basic read operation. There is no mention of being read-only, permissions needed, or any side effects. The description lacks transparency about what the tool does beyond its surface purpose.

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 (three sentences) and front-loaded with the core purpose. The second sentence about naming is arguably unnecessary but does not significantly detract from conciseness. Overall, it is efficiently sized.

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

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

Given the tool has 3 parameters, no output schema, and low schema coverage, the description is incomplete. It does not explain truncation behavior (max_chars), default project_root path, or return format. A more complete description would include these details 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?

The tool description adds meaning for the 'path' parameter by stating it is a 'relative path' to the artifact. However, it does not explain 'max_chars' or 'project_root' beyond what the schema already provides. With only 33% schema coverage, the description should compensate more.

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 reads a PAIDEIA course artifact by relative path. The verb 'Read' and resource 'course artifact' are specific. However, it does not distinguish from sibling 'read_artifact', which is presumably the same function without the PAIDEIA namespace.

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 only instructs to 'use this exact name when Alt searches for PAIDEIA__read_artifact', which is not a meaningful usage guideline. It fails to specify when to prefer this tool over sibling 'read_artifact' or other alternatives.

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

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

No annotations provided, so description carries burden. Mentions saving to canonical paths but does not disclose overwrite behavior, required permissions, error handling, or that parameters like project_root affect path resolution. Adds some behavioral context but incomplete.

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 serving a purpose: namespace alias clarification and core action. Could be slightly more concise by integrating the alias message, but overall 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?

Despite 7 parameters and no output schema, the description provides minimal context—no mention of return values, errors, parameter interactions, or prerequisites beyond implied canonical paths. Incomplete for agent 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 57% (4 of 7 params documented). The description only mentions canonical paths, adding no extra meaning to parameters like slug, content, overwrite, or answer_content. Meets baseline for partial 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?

Description states it saves PAIDEIA action outputs to canonical paths (e.g., quizzes/*). It differentiates from siblings by noting the namespace alias, but does not explicitly distinguish from similar tools like save_action_artifact or write_artifact.

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 the many sibling tools (e.g., write_artifact, save_action_artifact). Implies usage when saving PAIDEIA outputs but lacks exclusionary 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?

Without annotations, the description carries the burden. It does not disclose side effects, permissions, overwrite behavior (despite an overwrite parameter), error handling, or whether the operation is atomic. Only states it saves to three files in one call.

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 core purpose. The first sentence is somewhat redundant but not excessive. No fluff, 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?

Given 5 parameters (3 required) and no output schema or annotations, the description leaves gaps: no explanation of overwrite or project_root, no return value. It hints at the output directory but is not fully comprehensive for a save operation.

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 low (20% only for project_root). The description adds meaning by mapping summary_md, patterns_md, coverage_md to the respective files. Overwrite and project_root are not explained. Baseline 3 is appropriate given partial addition.

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 saves model-generated analyze outputs to three specific files (summary.md, patterns.md, coverage.md) in one call. The verb 'save' and resource are specific, distinguishing it from sibling tools like build_course_index. However, the first sentence about namespace alias adds redundancy.

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 only mentions to use the exact name for searches, not the scenario of use. Missing context on prerequisites or when not 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 provided, so description must disclose behavior. It mentions saving and appending errors but does not explain side effects (e.g., overwrite behavior, directory creation), permissions, or return value. Major gaps for a filesystem-writing tool.

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

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

Two sentences, but the first is extraneous meta-instruction about naming. The functional description is efficient but could be more focused. Not excessively long but not optimally concise.

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 6 parameters and no output schema, description is incomplete. Missing details on return value, error handling, overwrite behavior, and relationship to other tools. Leaves significant gaps for an agent to use 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%; description adds some context (e.g., model-generated report, appending errors) but does not clarify undocumented parameters like report_md or overwrite. Partially compensates 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?

Description states it saves a grading report under a specific path, which is clear. However, it does not differentiate from the sibling 'save_grade_report' tool, and the first sentence is a namespace alias instruction rather than clarifying 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?

No guidance on when to use this tool versus alternatives. No prerequisites or context provided. The only instruction is to use the exact name, which is about naming, not 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, the description carries the full burden. It lacks information about side effects (e.g., whether existing files are overwritten), permissions needed, or behavioral details like the effect of the 'mode' parameter. The description only hints at the action broadly.

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 fluff, but the second sentence largely restates the first. It could be more informative while remaining concise.

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

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

Given the tool has 5 parameters, no output schema, and no annotations, the description is incomplete. It doesn't explain the return value, error scenarios, or how parameters interact. The agent would lack critical context for correct 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 description coverage is only 20% (only 'project_root' has a description). The tool description adds no additional meaning to parameters like 'path', 'content', 'mode', or 'create_parent'. It fails to compensate for the schema's lack of clarity.

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 'Write/append/create' and the resource 'PAIDEIA markdown artifact' with location 'under the course root'. However, it does not explicitly distinguish this tool from its sibling 'write_artifact' (without prefix), which might cause confusion.

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 only mentions to use this exact name when Alt searches, which is not a meaningful usage guideline. It neither specifies when to use this tool nor contrasts it with alternatives like 'write_artifact' or 'PAIDEIA__read_artifact'.

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 the input format but does not mention whether the tool has side effects, requires authentication, or what it returns.

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 with no waste, but it is too sparse for a tool with no output schema or annotations. Some additional detail on expected usage or output would be appropriate.

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 and no annotations, the description is incomplete. It does not explain what the parsed result looks like or how it can be used, which is essential for a parsing 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 input schema has no parameter description (0% coverage), and the tool description adds minimal detail beyond stating the export type. The single parameter 'export_md' is not explained in terms of format or expected content.

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 parses an OPTIMETA Exam Radar exam-radar:v1 markdown export, specifying the exact format. However, it does not explain what the output of parsing is, leaving some ambiguity.

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 vs alternatives like import_exam_radar or parse_paideia_repo. The description lacks contextual usage instructions.

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, and the description does not disclose behavioral traits such as whether the operation is read-only, requires specific permissions, or has side effects. The term 'parse' suggests a read operation, but this is not explicit.

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, focused sentence. It is concise and front-loads the main purpose, though it could be slightly more structured.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is mostly adequate but lacks information about the output format or any side effects, which would be useful for an agent.

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 already describes the repo_root parameter, but the description adds valuable context about auto-discovery behavior when omitted, which aids 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 clearly states the verb 'parse', the resource 'PAIDEIA repo', and the outcome 'canonical action catalog', distinguishing it from sibling tools like list_paideia_actions or ingest_pdfs.

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. There is no mention of prerequisites or exclusions, 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.

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

No annotations provided, so description must disclose behavior. It only states the basic action, omitting whether the tool is read-only, side effects, output format, or any constraints like requiring a valid project root.

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

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

Single sentence is very concise and front-loaded with the main action. However, it sacrifices completeness for brevity; adding a second sentence about output or usage would improve without losing 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 tool with 3 params and no output schema or annotations, the description should at least explain expected output, how filtering works, and parameter roles. It only provides a minimal filter action, leaving gaps for correct agent 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 only 33%, but description adds no parameter-specific detail. It mentions 'by Pk label or keyword' but does not explicitly map to the 'query' parameter, and ignores 'max_chars' and 'project_root' parameters. The description fails to compensate for low schema coverage.

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

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

Description clearly states the action (filter), resource (course-index/patterns.md), and method (by Pk label or keyword). It distinguishes from sibling tools like build_course_index or save_course_index, which serve different purposes.

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

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

Usage is implied: use when you need to filter patterns. However, no explicit guidance on when to use versus alternatives, nor any prerequisites or exclusions are mentioned.

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

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

No annotations are provided, so the description carries full burden. It only says 'compose' but does not disclose whether the tool modifies state, requires authentication, has side effects, or what constitutes a successful composition. Behavioral traits are largely absent.

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

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

The description is a single, concise sentence that front-loads the core purpose. It avoids unnecessary words, though a slightly more structured breakdown could improve clarity for complex parameters.

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 no annotations, the description is too brief. It does not explain the tool's return value, error conditions, or dependencies (e.g., whether PAIDEIA must be installed). The context signals indicate moderate complexity, but the description fails to address completeness.

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 60%, with 'action', 'project_root', 'repo_root', and 'include_instruction' described in the schema. The description adds that the tool composes 'original PAIDEIA instruction, current workspace context, and output contract', which loosely connects to 'action' and 'project_root', but does not add detailed semantics for each parameter. The 'args' parameter lacks any 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 uses a specific verb ('Compose') and identifies three resources (PAIDEIA instruction, workspace context, output contract) that define the tool's output. It clearly indicates the tool prepares something for an Alt local model, but does not explicitly differentiate it from sibling tools like 'alt_workflow_guide' or 'course_phase'.

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, no prerequisites, and no when-not-to-use conditions. It simply states what the tool does without contextual instruction for the AI agent.

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, and the description provides minimal behavioral info: only that it reads (non-destructive). No mention of error handling, authentication requirements, or what happens for missing paths.

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

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

Single sentence, efficient and front-loaded. However, space could have been used to add one more clarifying sentence without losing 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?

Given no output schema and 3 parameters, the description is too sparse. It fails to explain what an artifact is, return format, or potential errors, leaving the agent underinformed.

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

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

Schema description coverage is low (33%), and the description adds little beyond the schema. The 'path' parameter lacks any description in both schema and tool description. No explanation of max_chars.

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 'Read' and the resource 'PAIDEIA course artifact', with the qualifier 'by relative path'. It distinguishes from sibling tools like list_artifacts and write_artifact.

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 (e.g., list_artifacts to discover artifacts). The description lacks context for appropriate usage scenarios.

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

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

With no annotations, the description must fully disclose behavior, but it only mentions saving to canonical paths. It does not explain file system side effects, validation, or the overwrite flag's exact behavior, leaving 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 conveys the core purpose. It could be slightly improved with structure (e.g., bullets) but is not verbose.

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 7 parameters, low schema coverage, no output schema, and no annotations, the description is too sparse. It lacks information on prerequisites, error conditions, and return values, making it incomplete for safe 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 57%, and the description adds value by listing canonical path patterns, but it does not explain parameters like slug or target_path in detail. The description partially compensates but is not comprehensive.

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 (save) and the resource (PAIDEIA action output) with specific canonical paths like quizzes/*, twins/*, etc. It distinguishes the tool from generic siblings like write_artifact by specifying the context of PAIDEIA workflow.

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

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

The description provides no guidance on when to use this tool versus siblings like prepare_paideia_action or write_artifact. It lacks explicit context, prerequisites, or exclusions, leaving the agent to infer 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?

No annotations provided. The description does not mention whether this is destructive, idempotent, or if it requires specific permissions. The schema includes an 'overwrite' parameter but the description omits its behavior.

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

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

The description is a single clear sentence but lacks important details. It could be restructured to front-load key information and reduce ambiguity.

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, 3 required, and no output schema, the description is insufficient. It omits the default behavior of overwrite, the relationship between parameters, and any side effects.

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 project_root described). The description does not explain the three required markdown parameters beyond their file names, leaving ambiguity about content expectations.

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 ('Save') and the specific resources (three predefined files in course-index directory). It distinguishes from sibling tools that write to generic artifacts or build indexes.

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 like build_course_index or write_artifact. No context about prerequisites or when not to use.

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

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

With no annotations, the description must fully disclose behavior. It mentions saving under 'answers/converted/' and appending errors, but lacks details on side effects (e.g., directory creation), required permissions, or error handling for missing fields.

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

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

Single sentence with no extraneous wording. Core action 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?

Despite having 6 parameters, no output schema, and no annotations, the description is too brief. Missing context about the 'errors' array, 'report_md' expectations, and the effect of 'overwrite'.

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 66.7% (4 of 6 parameters described). The description adds no new parameter information beyond the schema; it does not explain the 'errors' structure or 'report_md' format.

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 saves a model-generated grading report and appends error-log entries. It uses specific verbs and resources ('save', 'grade report', 'append error-log entries'), but does not differentiate from sibling tools like 'append_error' or 'write_artifact'.

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 siblings. There is no mention of prerequisites, alternatives, or when not 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 provided, so description carries full burden. It mentions three modes but does not disclose side effects like overwriting existing files, creation of parent directories (default true), or any required permissions. Lacks details on behavior beyond mode enumeration.

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 a single concise sentence, but it is too brief for the complexity of the tool (5 parameters). It lacks structure or elaboration that would help an agent interpret it correctly.

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

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

Given the complexity (5 params, no output schema) and low schema coverage, the description is severely incomplete. It omits return values, error handling, effects on the artifact system, and how to properly use parameters like project_root.

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 only 20% schema description coverage, the description adds no value to understanding parameters. It does not explain path, content, mode, create_parent, or project_root beyond the schema's own sparse descriptions.

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

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

Description clearly states the tool writes/appends/creates a PAIDEIA markdown artifact under the course root. The verb 'write' and resource 'artifact' are specific, and it distinguishes from siblings like read_artifact and list_artifacts.

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 siblings. No mention of when to use write, append, or create modes, or prerequisites like project_root being set correctly.

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