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

With no annotations, the description carries the full burden. It discloses the required environment variable (SYSTEMLINK_MCP_ALLOW_WRITE=1), the internal API (NotebookClient.create_executions), async queuing behavior, and parameter stringification. No contradictions.

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

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

The description is six sentences, with the purpose and prerequisite in the first sentence and parameter details at the end. Every sentence adds value without 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?

All key aspects are covered: purpose, permission, async behavior, and parameter semantics. The output schema handles return values, so no need to describe them here. Adequate for agent selection and 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 schema provides no parameter descriptions, so the explanation of notebook_id, workspace_id, and parameters adds crucial meaning. It clarifies the optional parameters are stringified for the SDK, which is not inferable from 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 opens with 'Start a SystemLink Jupyter notebook execution,' a specific verb+resource that clearly states the action. It further clarifies it queues work rather than returning output, distinguishing it from sibling query/listing 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 notes it does not wait for completion or return notebook output, implying that agents needing results should use a different tool (e.g., query_results). However, it does not explicitly name alternative tools or provide a when-not-to-use statement.

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

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

With no annotations provided, the description carries the full burden and does well: it notes that 'Step payloads are summarized' and only failing steps are previewed, and it documents the 50-cap on preview_limit. It misses minor details like side-effect absence or error handling, but covers key behaviors effectively.

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 and front-loaded with the core purpose in the first line. Every sentence adds value, from the DUT-context to the summarized payload warning, and ends with clean parameter documentation. No fluff.

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

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

For a simple read-only tool with two parameters and an output schema, the description covers purpose, parameter semantics, and a key behavioral constraint (cap). It doesn't address empty-result behavior, but that is minor for this complexity level.

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

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

The schema provides only types and defaults, so the description must add meaning, and it does: result_id is clearly defined as 'Test Monitor result id' and preview_limit as 'Max failing steps to include (capped at 50)', adding the critical cap information absent from 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 first sentence explicitly states the tool returns failing steps for one test result with measurements versus limits, using a specific verb and resource. The phrase 'DUT-debug view' adds important context that differentiates it from sibling tools like summarize_yield or query_results, which have 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?

The description provides clear context for when to use the tool ('This is the DUT-debug view') and implies its role in debugging failing steps. However, it does not explicitly name alternatives or provide exclusion criteria, which prevents a higher score.

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

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

With no annotations provided, the description carries the full burden and does well by disclosing default statuses (PAST_RECOMMENDED_DUE_DATE and APPROACHING_RECOMMENDED_DUE_DATE) and the cap on preview_limit. It does not cover every edge case, but what is disclosed is valuable and goes 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 front-loaded with the core purpose in the first sentence, followed by necessary context and parameter details—all in under 80 words. Every sentence earns its place with no redundancy.

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

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

For a simple read-only list tool with two optional parameters and an output schema, the description covers all necessary context: what it does, default statuses, parameter semantics, and limits. No additional details are 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?

Despite 0% schema description coverage, the description thoroughly explains each parameter: include_out_for_calibration toggles OUT_FOR_CALIBRATION assets and preview_limit is a max with a cap. This fully compensates for the lack of schema descriptions and adds 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 immediately states a clear verb+resource+scope: 'List instruments whose calibration is overdue or approaching due.' It also provides specific default statuses and ties the purpose to a PXI-fleet context, distinguishing it from generic wrappers.

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 clearly implies when to use the tool ('which chassis or module needs cal, and when') and contrasts it with a generic CMMS wrapper, giving strong contextual guidance. However, it does not explicitly state when not to use it or name alternative sibling tools, so it falls just short of a 5.

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

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

There are no annotations, so the description carries the behavioral burden. It does disclose two meaningful behaviors: it does not download file contents, and preview_limit is capped at 50. However, it does not mention what happens when no identifiers are provided, whether multiple lookup modes compose as union or intersection, or whether read access is always granted.

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 front-loaded with a one-sentence purpose, followed by tightly scoped bullets for each parameter. Every sentence adds information, and there is no filler or repetition. It is appropriately sized for the tool's moderate complexity.

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 output schema exists and all parameters are described, the description is largely complete for a simple file-metadata listing operation. The main gap is the lack of guidance on edge cases such as omitting all three identifier parameters or supplying multiple identifier sources simultaneously, but this is a minor omission for a read-only list tool.

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

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

Schema description coverage is 0%, but the description compensates by explaining all four parameters in plain language: explicit file ids, result-attached files, asset-linked files, and the preview cap. It adds real meaning beyond the raw schema, though it stops short of clarifying parameter interactions or expected value formats.

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 and resource: 'List file metadata attached to a result or asset.' It also clarifies scope by stating it does not download contents, which distinguishes this metadata-listing tool from anything that fetches file bodies. The sibling context further confirms this is the file-listing operation, not a general query 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?

The parameter descriptions provide clear context for using file_ids, result_id, or asset_id as lookup routes, which implies when the tool applies. However, it never explicitly contrasts this tool with siblings like query_results or query_assets, and it does not state whether the inputs are mutually exclusive, combinable, or authoritative when multiple are supplied.

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 burden. 'Query' implies a non-mutating look-up, but there is no explicit statement that there are no side effects, no auth requirements, no rate limits, no mention of behavior for missing entries, and no return format or cursor semantics. It gives the minimum needed information but does not go beyond what the schema already says.

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

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

The description is compact and front-loaded. The main verb is in the first line, each parameter is a bullet list or a line of its own; no filler words, no redundancy with the schema.

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 context (output schema: true; annotation: none) and the sibling list are simple. The tool has a clear assetInventory and supplies; no return value because an output schema is present. The description doesn't provide examples or use cases, but the essentials are all present. Since schema is present and the tool is a query, the absence of return value documentation is acceptable.

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

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

Schema coverage is 0% according to the context, so the description needs to compensate. It lists all 5 parameters with accurate, useful meaning: name = substring match, serial_number = exact, model = substring match, calibration_status = status enum values, preview_limit = cap (max 50). It adds concrete format details such as capitalization and the PXIe-6368 example, which are not present in the schema. Yet it could be more structured and exhaustive (e.g., the serial_number exact 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 uses a specific action ('Query') and a clear resource ('the asset inventory') with the key data dimensions listed (serial, presence, calibration state). This clearly distinguishes it from several sibling tools that query systems, products, specs, or files.

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 context is clear: checking the asset inventory. The parameter semantics moreover indicate the function of the filters. However, no explicit exclusion or explicit naming of the sibling alternative tool 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 mentions preview_limit is capped at 50, which is useful, but does not disclose whether the tool is read-only, what happens with no filters, or any rate limits or auth requirements. For a query tool with no annotations, this 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 concise and front-loaded with the purpose, followed by a compact parameter list. Each sentence earns its place, though the parameter list could be more integrated with the schema rather than duplicating it.

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 an output schema, so return values are covered. However, with no annotations and a query tool that likely has filtering semantics, the description could explain how filters interact (e.g., are they ANDed?) and what happens when no filters are provided. The cap on preview_limit is disclosed, but other behavioral details are missing.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain each parameter's meaning (family, part_number, name, preview_limit) and notes preview_limit is capped at 50, which adds value beyond the schema. However, it doesn't clarify that all filters are optional or how they combine (AND vs OR), which would be 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 states the tool queries products and part numbers used to correlate test results by revision, which is a specific verb and resource. It distinguishes from siblings like query_results and query_specs by focusing on product/part number data, though it doesn't explicitly name alternatives.

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

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

The description implies usage for correlating test results by revision, but does not explicitly state when to use this tool versus query_specs or query_assets. No exclusions or alternative tool names are provided, so 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, the description carries the transparency burden. It discloses that results are bounded, the preview is newest-only, preview_limit caps at 50, and date filters are inclusive ISO-8601 UTC. This provides solid behavioral context for a query tool, though it omits edge cases like empty-result 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 tightly structured: a one-sentence summary, two critical behavioral constraints, then concise parameter bullets. Every sentence provides necessary information without redundancy.

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

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

The tool has a rich output schema, so return-value explanation is unnecessary. Given the 7 optional parameters and no required inputs, the description fully covers input semantics, behavioral boundaries, and the core query purpose.

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?

Even though schema description coverage is 0%, the description documents all 7 parameters with practical meaning and constraints: status filter examples, inclusive date semantics, and preview_limit cap. This adds significant value beyond the raw schema definitions.

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

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

The description clearly states a specific action ('Query test results') and defines the exact return shape ('counts plus a bounded recent preview'). It differentiates itself by noting it 'does not dump the full result set', distinguishing it from potentially broader query 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 implies usage when a summary plus limited preview is needed, and explicitly warns against expecting full result dumps. However, it never names alternative tools or provides explicit when-to-use vs when-not-to-use guidance against the 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It adds useful context beyond the schema by explaining that product_id can be a simulation part number and that preview_limit is capped at 50. It does not mention error handling or permissions, but the query nature and output scope are reasonably 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 compact and front-loaded with the core purpose in the first sentence. The parameter explanations are brief and directly useful, with no filler or redundancy. Every sentence earns its place.

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

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

Given the low complexity, the presence of an output schema, and the clear parameter explanations, the description is largely complete. It covers purpose, parameter behavior, and a key constraint (cap at 50). It could be slightly stronger with explicit guidance on when to choose this over sibling query tools, but overall it is sufficient.

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

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

Schema description coverage is 0%, so the description must compensate, and it does. Both parameters are explained: product_id is defined as 'Product id or, in simulation, the part number used as product_id,' and preview_limit is described as 'Max specs to include (capped at 50).' This adds meaningful semantics beyond the raw 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 function: 'Query specification limits for a product' with specifics about the output (min / typical / max, unit). It distinguishes itself from siblings like query_products and query_results by focusing on specification limits rather than general product data or 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 you need specification limits for a product. However, it does not explicitly contrast with sibling tools like query_products or summarize_measurement, nor does it state when not to use it. The context is clear but the exclusion/alternative guidance is absent.

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 of behavioral disclosure. It provides some useful behavior details, such as substring matching, filtering on status.data.http_connected, and the preview_limit cap at 50, but it does not explicitly confirm this is a read-only operation or explain whether connection health is actively probed or reflects cached 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?

The description is compact and front-loaded, with a clear one-sentence purpose followed by concise parameter definitions. No redundant or filler content exists; every line adds value.

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

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

For a simple optional-parameter query tool with an output schema, the description covers purpose, filtering behavior, and parameter semantics well. It could go slightly further by noting the response shape or data freshness expectations, but the output schema already mitigates the need to describe 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?

With 0% schema description coverage, the description fully compensates by explaining each parameter beyond the schema. It clarifies alias as a substring, connected as a filter on a specific status field, and preview_limit as a maximum capped at 50—useful semantic details not present in the raw 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 'Query registered test systems and their connection health,' identifying both the specific resource (registered test systems) and the scope (connection health). This distinguishes it from sibling query tools like query_assets, query_products, and query_specs, which operate on different resource types.

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 purpose statement implies when to use the tool—when you need test system information and connection health—but it does not explicitly state when not to use it or provide alternatives. No exclusions or comparisons to sibling tools are offered.

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 some behavioral details, such as using DataFrameClient.query_decimated_data on a live server and not downloading every row, which implies a performance-oriented approach. However, it does not explicitly state side effects, error conditions, or whether the operation is read-only. The mention of 'downsampled trace preview' and 'stats' gives partial transparency but could be more 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 concise, with the main explanation in two sentences and then a brief parameter breakdown. While the parameter list is repeated in the schema, it adds clarity without being overly verbose. The structure is logically organized and easy 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?

The description does not specify the output format or structure of the summary, nor does it mention potential errors or edge cases (e.g., what happens if neither table_id nor result_id is provided). Given the lack of an output schema, the description could be more complete by explaining what the returned stats and trace preview contain.

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 provides helpful explanations for each parameter (table_id, result_id, preview_limit) that go beyond the schema. It clarifies the relationship between table_id and result_id (result_id is used if table_id is omitted) and defines preview_limit as a capped maximum. Since the schema itself lacks descriptions, this added semantic information is valuable.

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

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

The description clearly states the tool's function: summarizing a measurement table with stats and a downsampled trace preview. It is specific about the resource (measurement table) and the action (summarize), though it does not explicitly distinguish itself from sibling tools like summarize_yield, which might also produce summaries.

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 guidance on how to use parameters (e.g., 'Pass table_id directly, or result_id to use the first attached data table') but lacks explicit direction on when to choose this tool over alternatives such as summarize_yield or query_results. There is no mention of scenarios or prerequisites for using this tool instead of others.

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?

Notes that it uses Test Monitor result-level status rather than CMMS work-order counts and mentions server-side Dynamic LINQ filtering, adding context beyond basic operation.

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?

Well-structured with a brief intro and parameter list, but the explanations are somewhat repetitive without being bloated; still 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?

Covers filtering, grouping, and data source, and the output schema exists, so no need to explain return values; lacks explicit edge-case or error handling info but is adequate.

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

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

Provides clear explanations and examples for all 7 parameters, covering meaning, format, and usage, which significantly supplements the bare 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?

Clearly states it summarizes pass/fail yield for test results and distinguishes from CMMS work-order counts, 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?

Implies usage via the filter parameters and the yield summary function, but does not explicitly contrast with sibling tools like query_results or summarize_measurement.

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?

It discloses the write requirement (SYSTEMLINK_MCP_ALLOW_WRITE=1) and clarifies that keywords are replaced and properties are merged. It does not mention side effects or error conditions, but the update nature is clear.

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

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

The description is compact and well-organized, with a brief overview, a requirement note, and a clear parameter list. No unnecessary words.

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

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

It includes relevant context about the write requirement and a limitation regarding asset metadata. It does not describe the return value, but the output schema may cover that; overall it is sufficiently complete for an update 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?

All three parameters are explained: result_id is the identifier, keywords is a replacement list, properties are merged. This adds meaning beyond the schema's type 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 tool's function: 'Update keywords or properties on a test result.' It is specific and distinguishes itself from query-related 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 mentions a required environment variable and notes that asset metadata cannot be patched via another client, implying this tool is for test results. However, it does not explicitly compare with alternatives or state when not to use it beyond the asset limitation.

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