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

No annotations are provided, so the description carries full burden. It discloses no behavioral traits (e.g., read-only, destructive, authentication needs). The agent learns nothing beyond the tool's 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?

A single sentence with no wasted words. However, it could be longer to provide needed detail 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?

With 8 parameters, no output schema, and no annotations, the description is grossly inadequate. It explains neither the meaning of 'context' nor how parameters like seed_ids, max_tokens affect output.

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

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

Schema description coverage is only 13% (only 'root' has a description). The description adds no parameter information, failing to compensate for 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 states it 'Build compact task-specific context from project documents,' providing a specific verb and resource. It clearly distinguishes from sibling tools, none of which claim to build context.

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 when-not or context-specific advice 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?

The description does not disclose behavioral traits beyond the minimal 'create' action. It mentions no side effects, permissions, or behavior of the dry_run parameter. With no annotations provided, the description fails to inform the agent about write semantics or reversibility.

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

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

The description is very concise (one sentence), but it sacrifices valuable information. It is not front-loaded with key details; it only states the obvious. Conciseness is achieved at the expense of completeness.

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 (10 parameters, 6 required, no output schema, no annotations), the description is severely incomplete. It does not explain what an Engineering Decision Record is, how to structure the fields, or what the tool returns. The agent lacks essential 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?

Schema description coverage is only 10% (only 'root' has a description). The tool's description does not explain any parameter meanings, including required fields like 'title', 'context', 'options', etc. This leaves the agent without necessary context for proper parameter usage.

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 (create) and the resource (Engineering Decision Record), but does not differentiate from sibling tools like engi_requirement_create or engi_task_create, which could also involve creation decisions.

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 (e.g., engi_requirement_create for requirements, engi_task_create for tasks). The description lacks context on prerequisites, exclusions, or typical 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 provided, the description must fully disclose behavioral traits. It states 'create', implying a write operation, but does not mention side effects, idempotency, overwrite behavior, or required permissions. This is insufficient for safe agent usage.

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

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

The description is a single sentence, which is concise and front-loaded, but it omits necessary details for a tool with 8 parameters. It achieves conciseness at the cost of completeness, which is acceptable only for very simple tools.

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 8 parameters, low schema coverage, no output schema, and no annotations, the description is severely incomplete. The agent lacks information to understand the purpose of parameters, expected inputs, or return values, making effective invocation unlikely.

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 13% (only 'root' has a description), and the tool description adds no parameter semantics. Critical parameters like 'id', 'kind', 'path', 'template', and 'frontmatter' remain unexplained, leaving the agent unable to use them correctly.

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 specifies the verb 'create', the resource 'Markdown document', and the use of a 'template', which distinguishes it from sibling tools like engi_doc_read and engi_doc_patch_section. However, it does not specify what templates are available or the project context, 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?

The description provides no guidance on when to use this tool versus alternatives like engi_decision_create or engi_requirement_create. It lacks any prerequisites, context, or exclusions, forcing the agent to guess based on the tool 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?

With no annotations, the description carries full burden for behavioral disclosure. It only states 'Patch' without explaining side effects, whether modification is in-place, or what happens to existing content. Crucial behavioral traits (e.g., that operation modifies the file) are implied but not explicitly stated.

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 states the core purpose. However, it is overly minimal and does not earn its place by providing additional context; it could be expanded 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 the complexity (6 parameters, 4 required, an enum operation, and no output schema), the description fails to explain essential aspects like the effect of different operations, the format of heading_path, the role of dry_run, or the return value. The description is too sparse for an agent to use the tool confidently.

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 'root' described). The tool description adds no explanation for any of the six parameters, including critical ones like 'operation', 'heading_path', and 'dry_run'. The agent must rely solely on the schema, which lacks descriptions for 83% of 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 specifies the action ('Patch') and the resource ('Markdown section by heading path'), clearly distinguishing it from sibling tools like engi_doc_create (create full doc) and engi_frontmatter_patch (patch frontmatter only). However, 'patch' is somewhat vague without elaboration of the operation parameter.

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

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

The description provides no guidance on when to use this tool versus alternatives such as engi_doc_patch_section vs engi_doc_create or engi_frontmatter_patch. No context is given about prerequisites or 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, description carries full burden. 'Read' implies non-destructive operation, but no additional behavioral details (e.g., permission needs, behavior on missing document, content format). Minimal value beyond the name.

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, no waste. However, given 4 parameters and no output schema, the description is too concise to be adequately informative. It sacrifices completeness for brevity.

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

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

For a tool with 4 parameters (one enum), no output schema, and no annotations, the description lacks crucial context: what 'mode' does, what the return value looks like, error handling, and how it differs from sibling read-like tools (none exist directly but differentiation from create/patch is trivial). Incomplete for effective use.

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

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

Schema description coverage is only 25% (only 'root' described). Description adds meaning for 'id' and 'path' (identifiers) but omits 'mode' entirely. The 'mode' enum with five options is unexplained, leaving the agent guessing about summary vs. full content, etc.

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 verb 'Read' and resource 'managed Markdown document', with key identifiers 'ID or path'. Immediately distinguishable from sibling tools like engi_doc_create (create), engi_doc_patch_section (patch), and engi_frontmatter_patch (patch).

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 explicit when-to-use or when-not-to-use guidance. The description implies usage for reading documents by ID or path, but lacks context on choosing between ID and path or scenarios requiring different modes. No alternatives mentioned, though sibling names provide implicit direction.

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 does not disclose any behavioral traits such as idempotency, destructive potential, authorization requirements, or side effects. With no annotations provided, the description carries full responsibility for transparency, and it fails to give any operational details beyond the basic 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 a single concise sentence that clearly states the core function. It is front-loaded and contains no unnecessary words. However, it is too minimal to fully inform the agent, sacrificing completeness for brevity.

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

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

Given the tool's complexity (4 parameters, nested objects, no output schema, low schema coverage), the description is highly incomplete. It does not explain the patch semantics, the role of dry_run, how root and id are used, or any expected outcomes. The description does not sufficiently compensate for the missing structured information.

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 4 parameters with only 25% description coverage. The description does not mention any parameters or their semantics, leaving the agent to infer meanings from the schema alone. For example, 'patch' is an object but its structure and behavior (e.g., merge or replace) are not explained.

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 'patch' and identifies the resource as 'YAML frontmatter for a managed document.' It clearly states the action and target, but does not differentiate from sibling tools like engi_doc_patch_section which patches sections. Without explicit context, the distinction is implied but not stated.

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. There is no mention of prerequisites, exclusions, or context explaining when patching frontmatter is appropriate compared to other document 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 entirely shoulders the burden of behavioral disclosure. It only states the output ('dirty status and changed files') but does not indicate side effects (e.g., no writes), required permissions, or error conditions (e.g., not a Git repo). The minimal description leaves critical behavioral traits unspecified.

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

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

The description is a single short sentence with no wasted words. It conveys the core purpose efficiently. However, it could be slightly expanded to include key behavioral context without losing conciseness, which prevents 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?

Given the lack of annotations and output schema, the description is incomplete. It does not explain what 'dirty status' means, how results are formatted, or how the tool behaves in edge cases (e.g., no repository at root). The agent cannot fully anticipate the tool's output or errors from this description alone.

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% description coverage for the single parameter 'root', which already explains it as an absolute path to the project root. The description adds no further semantic information beyond what the schema provides, so a baseline score 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 uses a clear verb 'Return' and specifies the resource 'Git dirty status and changed files'. It is specific enough to convey the tool's purpose, and the tool name reinforces it. While it doesn't explicitly differentiate from sibling tools like 'engi_project_status', the Git-specific focus provides sufficient distinction for an agent.

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 such as 'engi_project_status' or 'engi_context_pack'. There is no mention of prerequisites (e.g., must be a Git repository) or context where this tool is appropriate. The agent lacks information to decide between similar 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 bears full responsibility for behavioral disclosure. It implies a read-only query ("return") but does not explicitly state that no modifications occur or specify any side effects.

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

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

The description is a single short sentence that is front-loaded and concise, but it may be too terse, providing minimal information without waste.

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

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

Given the tool has 5 parameters and no output schema, the description is insufficient. It does not explain what graph neighbors are, the output format, or how parameters like 'depth' or 'relation_types' affect results.

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 'root' has a description). The description itself adds no parameter meanings beyond the schema enums for 'direction' and 'relation_types'. Parameters 'id' and 'depth' remain unexplained.

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 graph neighbors for a document or entity, which is a specific verb and resource. It distinguishes from sibling tools like engi_impact_analyze and engi_project_map that focus on impact analysis or project mapping.

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 explicit guidance on when to use this tool versus alternatives. The description does not mention use cases, exclusions, or prerequisites.

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 behavioral traits. It does not mention whether the tool is read-only, permissions required, side effects, or return format. The brief description implies analysis but leaves ambiguity.

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 5-word sentence, which is too terse for a tool with 4 parameters and no other documentation. While concise, it sacrifices necessary detail and structure, making it 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?

No output schema and no annotations. The description does not explain what the output looks like, what 'transitive document impact' means, or any behavior beyond the bare verb. It is incomplete for an agent to effectively use 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 description coverage is only 25% (only root has a description). The tool description does not add any parameter explanations. It fails to clarify what 'changed_ids', 'depth', or 'change_description' mean, leaving the agent without enough context to correctly populate them.

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 specific verb 'Analyze' and resource 'transitive document impact for changed IDs', which distinguishes it from sibling tools like engi_graph_query that may analyze graph relationships but not specifically transitive impact for changed IDs.

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 engi_graph_query. The description lacks any context for appropriate usage 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 bears full responsibility. It does not disclose behavioral traits such as whether the tool is read-only, what happens if the root path is invalid, or if there are side effects. The description is too brief to convey any safety or behavior information.

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 unnecessary words. It is front-loaded with the core purpose. However, it may be too concise, omitting needed details.

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

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

Given the tool has 3 parameters, no output schema, and no annotations, the description is incomplete. It does not explain the structure of the returned tree, what 'managed' means, or how parameters like 'kind' affect results. Agents may misuse the tool without more 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 33% (only root has a description). The tool description does not explain the meaning or expected values of 'kind' or 'max_depth'. Agents would need to infer purpose from the names, which may be insufficient.

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 a tree/map of managed Markdown documents. The verb 'return' is generic, but combined with 'tree/map' and 'managed Markdown documents', it conveys a specific purpose. It distinguishes from sibling tools like engi_doc_read (read individual docs) and engi_graph_query (query graph), though not explicitly.

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

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

No guidance on when to use this tool versus alternatives. The description does not mention prerequisites, when not to use it, or which sibling tools to prefer for different tasks. For example, if a user wants a flat list, they might need engi_doc_read instead.

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 does not state whether the tool is read-only, what operations it performs, or any side effects. The behavioral traits (e.g., cost, permissions) are not disclosed.

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 but lacks structure. It does not use bullet points or separate sections for clarity. Some redundancy could be removed, but it 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?

Given the three parameters, no output schema, and no annotations, the description is incomplete. It does not explain what the returned status includes or how the boolean parameters modify the output. An agent may struggle 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?

The input schema has 3 parameters with only 33% description coverage (only 'root' has a description). The tool description adds no parameter-level information beyond the schema. For parameters like 'include_git_status', no explanation of how they affect the output is given.

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 returns a 'concise EngiMCP project status', but doesn't specify what information is included (e.g., validation results, git status). This is adequate but vague, and doesn't differentiate from siblings like engi_git_status or engi_validate_project.

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. For example, if a user needs only git status, engi_git_status is more appropriate. The description lacks any context for choosing this tool.

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

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

With no annotations provided, the description carries full burden. It only hints at auto-ID generation but omits important traits like destructiveness, 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?

A single sentence with no waste, but it lacks sufficient information. Acceptable conciseness but at the cost of completeness.

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 8 parameters (5 required), no output schema, and no annotations, the description fails to provide essential context such as required fields, behavior on error, or return values.

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 very low (13%); the description adds no parameter-level detail. For 8 parameters, this is insufficient to guide 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 tool creates a requirement document and mentions the auto-generated ID, but it does not differentiate from sibling tools like engi_doc_create or engi_decision_create, which may create similar documents.

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, nor any prerequisites or exclusions. The description merely states the action without 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. It only states 'Create,' implying mutation but omits details like side effects, permissions, or error conditions.

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 at one sentence, but it sacrifices necessary detail. While not verbose, it is 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 the tool has 6 parameters, no output schema, and no annotations, the description is incomplete. It does not explain what a 'project task document' is or how the parameters relate.

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 17%, yet the description adds no parameter information. It does not explain the meaning or usage of any of the six parameters, failing 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 'Create a project task document,' identifying the verb (create) and resource (project task document). However, it does not distinguish this from sibling tools like engi_doc_create or engi_decision_create, which also create documents.

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. The description lacks any context about prerequisites, scenarios, or exclusions.

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

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

Without annotations, the description carries full burden. It implies a non-destructive validation behavior but does not disclose side effects, permissions needed, or error handling. The brief statement is adequate but lacks depth.

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 7-word sentence, which is extremely concise. While every word is meaningful, the brevity sacrifices clarity needed for other dimensions. It earns points for being waste-free but loses some for being too terse.

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, no annotations, the description is insufficient. It does not explain validation rules, expected input formats, or return value structure. The agent is left guessing how to properly call 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 description coverage is only 33% (only 'root' has a description). The description does not compensate by explaining the meaning of 'checks' or 'severity' parameters. The agent gets no help understanding what validations are performed or how severity affects output.

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 'Validate' and specifies the resources: IDs, frontmatter, and basic document relationships. It distinguishes the tool from siblings like engi_doc_read (read-only) and engi_frontmatter_patch (modification), making its purpose unambiguous.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, when not to use, or how it compares to sibling tools like engi_context_pack or engi_graph_query that may also deal with document validation.

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