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

The description adds valuable behavioral context beyond the readOnlyHint annotation by disclosing what the tool does NOT return (raw evidence, result_detail, error_record). This helps the agent set expectations and avoid misusing the tool. The readOnlyHint is consistent with a read-only comparison 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?

The description is two sentences long, front-loaded with the core purpose, and every word adds value. The second sentence is a crisp exclusion that prevents misinterpretation. No fluff or repetition of schema 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?

The description, combined with the output schema, covers the core semantics well: what the tool does and what it excludes. However, it does not clarify the limit parameter's role (e.g., 'limits number of comparison items returned'), which is a minor gap. For a tool with this complexity, the description is nearly complete but not perfect.

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 must compensate. It hints that base_run_id and target_run_id are the two runs being compared, but it does not explicitly name them or explain the limit parameter. The description adds minimal meaning beyond the parameter names themselves, leaving the agent to guess at limit's behavior.

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 'Compare' followed by the resource 'summary result changes' and the scope 'between two runs.' It also explicitly differentiates from sibling tools by stating 'Not raw evidence; no result_detail or error_record,' which distinguishes it from get_result_detail and get_failed_tests.

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 clear context that this tool is for comparing summary-level results, not raw evidence or errors. While it doesn't explicitly name alternative tools, the exclusion of result_detail and error_record implicitly steers users toward get_result_detail or get_failed_tests when those are needed. This is clear enough but not fully 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?

Annotations already declare readOnlyHint=true, and the description adds further behavioral context by stating it returns only summaries and explicitly excludes result_detail or error_record. It does not mention pagination or default filtering, but the annotation covers the safety profile, so the extra detail earns a solid 4.

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 one compact sentence, front-loaded with the core purpose and immediately followed by a clarifying exclusion. Every word earns its place; no wasted content.

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

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

Given the presence of an output schema and a readOnly annotation, the description is sufficient for a filtered summary tool. It clearly delineates scope but leaves parameter semantics unexplained, which is a minor gap. Overall, it is complete for the tool's complexity but not perfect.

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% and the description does not explain the four optional parameters (limit, run_id, category, severity). The schema provides names, types, and defaults, but the description itself adds no meaning to these parameters, and with low coverage it fails to compensate.

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 'failed/error test summaries only', using a specific verb and resource. It also distinguishes from siblings by explicitly noting it does not return result_detail or error_record, which sets it apart from get_result_detail and other raw-evidence 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 when to use the tool (when failed/error summaries are needed) and excludes raw evidence use, but does not explicitly name alternative tools. It provides clear context via negative constraints, though it could be stronger by naming a sibling like get_result_detail for raw evidence.

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 readOnlyHint annotation already indicates a safe read operation, and the description adds the access restriction 'Auditor-only,' which is not captured in annotations. This context is valuable for an agent deciding whether to invoke the tool. The description does not contradict the annotation.

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 brief, consisting of two short sentences. The first sentence is a fragment ('Auditor-only raw evidence') but still front-loads the core purpose. The second sentence gives usage guidance. No wasted words, though the fragment structure could be improved.

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 covers access restriction and usage conditions, and the output schema presumably documents return values. However, parameter semantics are entirely absent, which is a significant gap given the lack of schema descriptions. The tool's role within the sibling context is clear, but parameter context is 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?

The description provides no information about the two required parameters, run_id and test_id. With schema description coverage at 0%, the agent has only the parameter names to infer meaning. The names are reasonably self-explanatory, but the description fails to add any semantic value or clarify expected format or relationship.

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 the tool as returning 'Auditor-only raw evidence,' which combined with the name get_result_detail clearly indicates it retrieves raw result details. It also distinguishes itself from sibling getters by specifying it returns raw evidence rather than summaries or test lists. However, the description lacks an explicit verb, making it a noun phrase rather than a clear action statement.

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 explicit guidance: 'Use only when result_detail, error_record or script_block_file is requested.' This clearly states when the tool is appropriate and implies when it should not be used. It does not name alternative tools, but the condition is specific 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?

Annotations already provide readOnlyHint=true, and the description adds value by specifying the exact scope of the response and excluding certain data types. This helps set expectations about output beyond the annotation, which fulfills the behavioral disclosure requirement.

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 main purpose and adds exclusions efficiently. Every word earns its place, with no filler or redundancy.

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

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

The description covers the core purpose and exclusions, and the output schema covers return values. However, it misses critical context about the optional run_id parameter (e.g., what happens when null) and does not provide any usage guidance for obtaining a run_id or when to use this tool over siblings. These gaps leave it minimally 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?

The input schema has one parameter, run_id, with default null and no descriptions (0% coverage). The description does not mention run_id at all, failing to explain its meaning, how to use it, or what null indicates. Since the schema provides no help, the description needed to compensate but did not.

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

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

Description states the exact function with a specific verb+resource: "Return run summary counts only." It clearly distinguishes from siblings by listing exclusions (raw evidence, source path, source hash, result_detail, error_record), making the 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?

The description provides clear context for when this tool is appropriate (when only summary counts are needed) and explicitly states what it does not return, implying when not to use it. However, it does not name alternative tools, so the guidance is more implied 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?

Annotations already declare readOnlyHint=true, and the description adds valuable behavioral context by specifying that the tool returns only summary history and deliberately excludes result_detail and error_record. This clarifies data granularity and limitations beyond the annotation.

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

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

The description is extremely concise, with two short sentences that front-load the core purpose and key exclusions. Every word adds value, and it avoids unnecessary detail.

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 2-parameter tool with an output schema and read-only annotation, the description covers the essential selection criteria and data scope. It could mention the behavior of the limit parameter, but overall it is sufficiently complete.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meanings. It only implies test_id via 'test/control' but completely omits limit, leaving its meaning and default behavior 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 uses a specific verb 'Show' and resource 'summary history' for a test/control, clearly stating the tool's function. It also distinguishes from siblings by explicitly noting it does not return raw evidence, result_detail, or error_record, which sets it apart from get_result_detail.

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 (for summary history) and warns that it is not for raw evidence, providing context for selection. However, it does not explicitly name alternative tools like get_result_detail for raw evidence, so it falls short of full guideline clarity.

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

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

Annotations already declare readOnlyHint=true, and the description adds the context that data comes from a sanitised dataset. However, it does not disclose ordering, pagination, or what 'recent' means. The behavioral transparency is adequate but not enhanced beyond annotations.

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

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

A single, front-loaded sentence that contains no filler. Every word contributes to the purpose, making it highly concise and well-structured.

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

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

With an output schema present, return values are covered. The tool is simple with one optional parameter, and the description covers the core purpose. However, the lack of parameter semantics and vague 'recent' leaves some gaps for a complete understanding.

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 description coverage is 0%, and the description does not mention the 'limit' parameter at all. The agent must rely on the parameter name and default value, which is insufficient for understanding its semantics (e.g., how limit affects results).

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 the action ('List'), the object ('recent Maester runs'), and the data source ('sanitised DuckDB dataset'). This specific verb+resource combination distinguishes it from sibling tools that focus on summaries, histories, or comparisons.

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 listing runs but provides no explicit context about when to choose this over alternatives like get_run_summary or get_test_history. There is no mention of prerequisites or exclusions, making this a minimal viable 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?

The readOnlyHint annotation already establishes the read-only nature, and the description adds meaningful behavioral detail by specifying the exact information returned (caller and authorization context). This complements the annotation without contradiction.

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 starts with the action verb, includes no redundant words, and immediately communicates the tool's function.

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 parameters, an output schema present, and read-only annotations, the description fully covers the essential context. It clearly differentiates from siblings and leaves no gaps for such a simple tool.

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

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

The tool has zero parameters, and the input schema reflects this with 100% coverage. As a result, the description has no parameter meanings to convey, and the baseline of 4 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 the specific verb 'Return' and identifies a concrete resource: 'local caller and authorisation context'. This clearly differs from sibling tools that deal with runs, tests, and results, making its purpose unmistakable.

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

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

The description conveys a clear context for use—retrieving caller identity and permissions—without explicit alternatives. Given that all sibling tools focus on run/test data, the intended use case is obvious, but there is no explicit 'when to use' or 'when not to use' guidance.

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