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

There are no annotations, so the description carries the full burden of disclosing behavior. It does convey that the operation is non-destructive (append) and targets an existing file, but it does not state what happens if the file is missing, how line separators are handled, or what the result of appending looks like.

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, tightly worded sentence that front-loads the verb and target with no filler. It could have used the space to add usage or behavior notes, but as written it is appropriately 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?

For a low-complexity append operation with fully documented parameters and no meaningful return value, the description is largely sufficient. The only gaps are edge-case behaviors such as missing files, which are secondary to selecting and invoking 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 100% and both path and content already have clear descriptions. The tool description adds no additional parameter-level meaning, so 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 states a precise verb, 'append' (追加), and a specific resource, an existing Stata do-file (已有 do 文件). This clearly differentiates it from sibling tools like stata_write_dofile (create/overwrite) and stata_read_dofile (read) without needing to open the schema.

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

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

The phrase '已有' implies the file must already exist, and 'append' implies adding to rather than replacing content, so usage is inferable. However, there is no explicit when-to-use/when-not-to-use guidance or mention of alternatives such as stata_write_dofile for creating/overwriting.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal the mechanism: run `describe`, read the session's latest run log, and return basic info to the caller. However, it does not mention prerequisites (e.g., a dataset must be loaded), potential side effects on the session, or what happens on failure.

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

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

The description is a single, compact sentence that front-loads the core action (`运行 describe`) and then explains the mechanism and result. There is no redundant information or filler; every phrase contributes meaning.

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 adequate for a zero-parameter tool, but it leaves gaps: the exact meaning of '基本信息' is vague, there is no mention of required session/dataset state, and it does not clarify how this differs from `stata_get_data_schema`. Given there is no output schema or annotations, some additional context would help an agent 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?

The tool has zero parameters, so the baseline is 4. There is no parameter information missing, and the description does not need to compensate for undocumented inputs. The empty schema is consistent with the description's focus on an action without arguments.

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

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

The description clearly identifies the action: it runs Stata's `describe` command and returns basic information about the current dataset to the caller. It conveys the resource and outcome specifically, though it does not explicitly distinguish itself from the closely related sibling `stata_get_data_schema`.

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 about when to use this tool versus alternatives like `stata_get_data_schema` or `stata_get_results`. The intended context is implied by the tool name and description, but there are no explicit usage conditions 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?

There are no annotations, so the description carries the behavioral burden. It does disclose a meaningful implementation detail — the schema text log is independent and overwritten on every call. It does not mention potential side effects, required session state, or what happens if no dataset is loaded, but it provides more than a bare statement of 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 entire description is one sentence with no filler or repetition. It is compact, though the opening clause about the schema text log delays the main action slightly.

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

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

With no output schema and no annotations, the description gives only a broad sense of return content. It covers the data structure, missing summary, and sample preview, but omits usage boundaries, return format, or error conditions. It is adequate for a moderately simple read tool, 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?

Schema coverage is 100%, so parameters are already documented. The description loosely aligns with the parameters by mentioning sample preview and missing summary, but it adds no detail about defaults, combinations, or behavior 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 names a specific verb (read) and resource (current Stata dataset structure, missingness summary, and sample preview), and adds a unique mechanism (independent schema text log). It is clear, though it does not explicitly contrast with the similarly named sibling stata_get_data_info.

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

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

The intended use is implied: call this when you need the current dataset's schema, missing summary, or sample preview. However, it gives no explicit guidance about when to choose this over stata_get_data_info or stata_get_results, so alternatives are not addressed.

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

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

No annotations are present, so the description carries the full burden. It discloses that the tool executes commands and relies on the session's latest run log to extract results, which is useful context. However, it does not mention prerequisites (e.g., an active session or prior command producing r()/e()) or potential side effects of running commands, so it is only partially transparent.

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

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

The description is a single concise sentence that front-loads the action and then explains the delivery mechanism. There is no redundant phrasing; all included details (command execution, session log, result type) earn their place.

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

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

The tool has a simple input schema and no output schema, so the description needs to explain return values and prerequisites. It describes what is returned (r()/e() stored results) but does not specify the output format or note that a Stata session with recent results must exist, leaving modest gaps for an agent to call it correctly.

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

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

The schema already documents the `type` parameter (enum r/e) with 100% coverage. The description adds meaning by associating the type with the specific commands (`return list` vs `ereturn list`) and clarifying that returned values correspond to r() or e() stored results, going beyond the bare enum 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 states a specific action: it runs `return list` or `ereturn list` and returns the stored r()/e() results to the caller. It names the exact Stata commands and the result type, which clearly distinguishes it from siblings like `stata_run` and `stata_read_log`.

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

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

The description implies the tool is for retrieving Stata stored results after commands, but it does not explicitly state when to use it over alternatives such as `stata_read_log` or provide any exclusions. The use case is inferable but not spelled out.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the prerequisite that a Stata GUI must already be open, but it does not mention side effects of installation, network requirements, overwriting behavior, or failure conditions. For a mutating operation, this is a significant transparency 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 a single, front-loaded sentence that conveys the action, target, environment, and examples with no filler. Every part earns its place.

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

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

For a simple two-parameter installer, the description plus fully documented schema provide enough information to invoke the tool correctly. The main gaps are behavioral side effects and expected output, but these are not blocking for a basic install 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 description coverage is 100%, so the schema already fully documents both parameters: package names and source with an enum and default. The description adds example packages but no additional meaning beyond what the schema provides, matching the baseline for high schema coverage.

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

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

The description states a specific verb ('install'), a clear resource ('external packages'), and the environment ('in the already open Stata GUI'), with concrete examples like estout, ivreg2, and rdrobust. This clearly distinguishes the tool from sibling operations such as running commands, writing do-files, or reading results.

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

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

The description implies when to use the tool: when an external Stata package needs to be installed in an already-open GUI session. However, it does not explicitly compare it to alternatives such as stata_run, which could also execute an install command, nor does it state when not to use this tool.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does say the tool reads and returns content, which implies a non-mutating operation, but it does not explicitly state that it does not execute the do-file or trigger Stata, a relevant distinction from sibling tools like stata_run_dofile.

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

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

The description is a single front-loaded sentence with no redundant or filler content. It states the action, the resource, and the intended purpose efficiently.

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

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

For a simple one-parameter read tool, the description provides the essential context: what it reads and why. It could be slightly more complete by explicitly stating that it does not execute the file, but the use case is still clear enough for an agent 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?

The schema already documents the only parameter, 'path', with the description 'do 文件的完整路径', giving 100% coverage. The tool description adds no parameter-specific meaning beyond the schema, so the 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 states a specific action and resource: '读取 do 文件内容' (read do-file content). This clearly distinguishes it from sibling tools like stata_write_dofile and stata_append_dofile, and the purpose '检查、解释或继续修改' further clarifies its role.

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

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

The intended usage is implied by the purpose phrase '检查、解释或继续修改' — use this tool when Claude needs to inspect or modify a do-file. However, it does not explicitly name alternatives or state when not to use it, leaving usage guidance implied rather than explicit.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses the default path fallback and the parsing behavior of output_format='dict' into command-result pairs, which adds real value beyond the schema. It does not mention error conditions such as what happens when no prior session exists, but the disclosed behaviors are meaningful.

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

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

Two short sentences with front-loaded purpose and actionable defaults/recommendations. No filler, no repetition of schema content, and every clause adds useful information.

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

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

For a zero-required-parameter read tool with full schema coverage, the description covers purpose, default behavior, and recommended output format. It lacks an output schema and annotation safety profile, but the core invocation decision is adequately specified.

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

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

All three parameters are fully described in the schema, so the baseline is 3. The description adds important semantics for path (empty means recent session's last_log_path) and output_format (dict is recommended and parses logs into command-result pairs), which is value beyond the schema. tail_lines remains schema-only but already has a clear one-line 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 identifies a specific verb and resource: reading a Stata text log, and the log-vs-dofile distinction in sibling names makes the target reasonably clear. It does not explicitly contrast with stata_get_results or stata_read_dofile, so it stops short of full sibling differentiation.

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

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

It provides concrete usage context: leave path empty to target the most recent session's last_log_path, and prefer output_format='dict' when the AI needs to locate errors. It does not explicitly say when to use alternative tools, but the practical guidance is clear and actionable.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It explicitly mentions that the tool overwrites the session's latest run text log and returns actual output, which are important side effects. It does not mention error handling or permission requirements, but the disclosed behavior is clear and adds value beyond the schema.

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

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

The description is concise, with the primary action front-loaded and side effects and session-switching guidance following. It is two sentences with no fluff, and each clause carries information. It is slightly verbose due to phrasing, 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?

Given the tool's simplicity (one parameter, no output schema, no annotations), the description covers the essential context: the session to use, the side effect (log overwrite), the return of output, and how to switch sessions. It does not cover error handling, but that is not expected for a simple command executor. It is complete enough for an agent 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 description coverage is 100%, so the baseline is 3. The description adds a nuance by describing 'commands' as a 'complete code block', but does not provide additional syntax or format details beyond what the schema already states. It adds minimal semantic value beyond the schema.

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

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

The description clearly states the primary action: executing 'commands' as a complete code block in the most recent Stata session. It also mentions the side effect of overwriting the session's log and returning output, which adds specificity. However, it does not explicitly differentiate from sibling tools like 'stata_run_dofile', so it lacks explicit sibling distinction.

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

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

The description gives a usage hint by mentioning that one can switch the target session using 'stata_session(action='set_recent')', which is helpful context. But it does not explicitly state when to use this tool versus alternatives like 'stata_run_dofile' or when not to use it. The guidance is implied rather than explicit.

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

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

With no annotations provided, the description carries the full behavioral burden. It transparently discloses that each call overwrites the session's latest running log in .stata-mcp/cache/, automatically returns the log content, and does not modify the user's original do file. These are important side effects and constraints. It does not mention potential blocking behavior or error handling, but the disclosed information is substantial and accurate.

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 composed of a few sentences, with the primary purpose stated first. It includes essential behavioral details (log overwriting, return value, non-modification) without unnecessary verbosity. The structure is clear and efficient, though it could benefit from a slight reordering to front-load the most critical behavioral note about log overwriting.

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 that there is no output schema, the description explains what the tool returns (log content). It covers the key aspects an agent needs to know: setting up session_id for related tasks, the behavior of the log, and the safe handling of the original file. It does not mention return format or error handling in detail, but for a run tool with this parameter set, it is fairly complete.

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

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

The schema already provides 100% coverage with descriptions for all parameters. The description adds value beyond the schema by explaining the session_id semantics (same session for related tasks) and clarifying that log_mode is a compatibility parameter that always uses 'replace' in version 1.1. This enhances the agent's understanding of how to use the parameters 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 states the tool's purpose: running a do file in Stata GUI. It specifies the resource (do file) and the environment (Stata GUI). It is distinct enough, though it does not explicitly differentiate from the sibling 'stata_run' tool, which could be a potential confusion point. Overall the purpose is specific and unambiguous.

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

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

The description provides useful usage context: it explains the session_id concept (same session for original/check/continuation do files) and notes the behavior of overwriting the latest log. However, it does not give explicit guidance on when to use this tool versus alternatives like stata_run or stata_append_dofile. The context is helpful but not a full usage guideline.

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

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

Annotations are absent, so the description must carry the full behavioral burden. It does explain what session_id represents and what it is associated with, but it does not disclose the side effects of destroy, what get returns, how set_recent changes behavior, or whether these operations are safe or destructive. A session-management tool with a destroy action needs clearer behavioral disclosure.

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

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

The description is a single compact sentence that front-loads the tool's purpose and action list, then adds essential session-semantics context. There is no fluff or repetition of the schema. It could be slightly better structured by separating the action enumeration from the session_id semantics, but it remains appropriately 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?

With no output schema and no annotations, the description should clarify return values and behavioral outcomes for each action. It adequately covers what session_id means and which actions need it, but it does not explain what list/get return, what destroy removes, or what set_recent actually switches. The tool is simple enough that this is a moderate gap, not a fatal one.

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 goes beyond the schema by explaining that session_id identifies the same reproduction task/GUI and is linked to entry/source/current do and log paths. It also clarifies that get/destroy/set_recent require session_id, which is not reflected as a conditional requirement in 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 identifies the resource (Stata MCP session) and enumerates the four supported operations: list, get, destroy, and set_recent. This maps directly to the action enum and distinguishes the tool from siblings focused on running or editing do-files. '管理' alone would be vague, but the explicit action list makes the purpose concrete.

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 versus alternatives, and it does not explain when one action should be preferred over another. The action enum and the session_id note imply some usage contexts, but the description never states conditions like 'use list to discover active sessions' or 'destroy removes the session and its associated state.'

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 transparency burden. '检查' strongly implies a read-only inspection, and naming the project-local cache file adds useful concrete context about the data source. However, it does not explicitly state side-effect-freeness, permission requirements, or behavior when the registry file is missing.

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

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

The description is a single compact sentence that front-loads the action and lists its targets without filler. The inclusion of the specific cache file path is dense but relevant, and no sentence or phrase is wasted.

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 zero-parameter schema and the straightforward status-checking nature, the description adequately covers what the tool does and what it inspects. It does not spell out the exact response format, but for a status/inspection tool that information is largely inferable from the listed targets.

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?

This tool has zero parameters and an empty input schema, so there is no parameter documentation burden. The description still adds semantic value by explaining what the status check covers, which is sufficient for an agent to invoke the tool 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 uses the concrete verb '检查' (check/inspect) and identifies three specific objects: Stata MCP server status, in-memory sessions, and session/do/log relationships recorded in .stata-mcp/cache/task_registry.json. This resource-level specificity clearly distinguishes it from siblings like stata_run or stata_session, even without naming them. It is not a tautology and tells an agent exactly what the tool inspects.

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 is provided, and no sibling alternatives are named. The intended usage is implied by the content: call this tool to check server/session/cache status. However, it lacks explicit routing or exclusion conditions that would make this dimension stronger.

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 disclosure burden and does add meaningful behavior: it writes to disk, returns the file path, routes relative filenames to .stata-mcp/dofiles/, and notes that MCP runtime is not used. It does not disclose overwrite behavior or session prerequisites, but the disclosed traits are substantial.

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 dense, front-loaded senrence that includes action, return value, path semantics, and a runtime caveat. Every clause adds information; no filler.

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

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

For a simple two-parameter tool with full schema coverage, this is nearly complete: it specifies the return value, the default location behavior, and the runtime exception. It could be more complete about overwrite behavior or what happens if no session project exists, but those are edge cases.

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

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

Schema covers 100% of parameters, so the baseline is 3. The description adds no new parameter-level meaning beyond what the schema already states about filename and auto-generation; it mostly restates the path behavior already present in 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?

States a specific verb ('write'), a resource ('do file'), and the outcome ('saved to disk, returns file path'). The description clearly distinguishes this from sibling tools like stata_run_dofile or stata_append_dofile by focusing on writing and saving.

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 creating or overwriting do-files and clarifies path resolution for relative filenames, but it does not explicitly say when to prefer this tool over alternatives such as stata_append_dofile or stata_run_dofile. No when-not-to-use guidance is provided.

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