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

With no annotations, the description does the safety disclosure itself by saying `read-only` and by specifying it returns only the `latest` run. It does not mention authentication, rate limits, or what happens when no workflow run exists, but the read-only behavior is the most important trait.

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

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

One short sentence conveys the resource, scope, and safety profile with no filler. The most important information is front-loaded.

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

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

For a small read-only status lookup, the description and input schema together cover the necessary invocation details, and the output schema covers return values. It would be more complete with a note about when no runs exist, but nothing critical 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?

Schema description coverage is 0%, so the description must compensate, but it only gives context for `branch`. `owner` and `repo` are left to their self-evident names and the schema has no descriptions, so an agent receives little added semantic help.

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 the exact resource (`GitHub Actions workflow run`) and the scope (`for a branch`), and the `(read-only)` qualifier separates it from sibling GitHub mutation tools. It lacks an explicit verb like 'gets' or 'returns', which keeps it from a 5.

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

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

No guidance is given on when to choose this tool over siblings such as github_list_issues or github_pr_diff_summary, nor any exclusions for when it should not be used. The only hint is the title and the read-only label, which are implicit rather than stated.

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, and it delivers: it discloses symlink/.. escape fail-closed behavior, UTF-8 decoding with replacement characters, and the 'truncated' flag when the file exceeds the cap. This is exactly the kind of edge-case behavior an agent needs to know before calling the tool. No annotation 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?

Three sentences, each earning its place: the first states the core operation and constraint, the second covers security behavior, the third covers encoding and truncation. Front-loaded with the primary purpose. No fluff or repetition.

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

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

The description covers the key behavioral aspects: security (fail-closed), encoding (UTF-8 replacement), and size cap (truncated flag). The output schema exists, so return values are documented elsewhere. Minor gap: it doesn't specify what happens on non-existent files or permission errors, but the fail-closed language partially covers this. For a 2-param read tool with an output schema, this is nearly 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. It explains the 'max_bytes' cap implicitly via 'hard size limit' and 'truncated' flag, but it doesn't explicitly state that max_bytes is the cap parameter or describe the path format (relative vs absolute, allowlist details). The description adds some meaning beyond the bare schema (the size cap behavior), but the path parameter semantics are left to the schema's bare type string. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Read') and resource ('a file under allowlisted roots') with a hard size limit. It clearly distinguishes itself from siblings like fs_search (which searches) and the github/postgres tools. The scope constraint 'under allowlisted roots' adds precision beyond the tool name.

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 this tool: when you need to read a file's content under the allowlisted roots. It doesn't explicitly name alternatives or exclusions, but the sibling list makes the distinction clear (fs_search is for searching, not reading). The 'hard size limit' and 'fail closed' behavior give implicit guidance on constraints. Missing explicit 'use fs_search instead when...' guidance, but context is clear enough.

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?

Since no annotations are provided, the description carries the full burden. It discloses that the search is for a literal substring, that matches are confined to OPS_MCP_FS_ROOTS, and that paths escaping via '..' or symlinks are rejected. This is meaningful behavioral context about sandbox enforcement. It does not mention case sensitivity, recursion depth, or hidden-file behavior, so it is strong but not exhaustive.

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 short sentences, front-loaded with the core action and qualifier. The second sentence adds essential security scoping without fluff. Every phrase earns its place, and the formatting with backticks aids readability. It is an exemplar of concise, high-signal description.

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

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

The tool has 3 parameters, 1 required, and no annotation support. The description leaves 'max_results' completely unexplained and only vaguely gestures at 'root' through the sandbox mention. Although an output schema exists, the agent still needs parameter semantics to call the tool correctly. The lack of usage guidance compounds the incompleteness, making this insufficient for a frictionless call.

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 the schema's lack of parameter documentation. It clarifies that 'query' is a literal substring and that results are restricted to the allowlisted roots, which indirectly relates to the 'root' parameter. However, it never explains the 'max_results' parameter, its default, or how 'root' narrows the search. Two of three parameters are not explicitly mapped to their purpose.

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 searches allowlisted filesystem roots for a literal substring. The verb 'search' and resource 'filesystem roots' are specific, and the 'literal substring' qualifier distinguishes it from regex or fuzzy searches. Among siblings like fs_read_file, the purpose is distinct and immediately understandable.

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

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

The usage context is implied: this is the tool to use when you need to find a substring within allowed file system paths. However, there is no explicit guidance on when to prefer this over alternatives like fs_read_file, nor are there exclusion criteria or examples. The scope restriction to OPS_MCP_FS_ROOTS is stated, but not framed as a when-to-use condition.

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

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

With no annotations provided, the description carries full behavioral disclosure. It reveals the dry_run default (no remote write) and the guarantee that credentials are never returned, which are important behavioral traits. However, it does not explain what happens on failure, whether the operation is idempotent, or what the successful response contains, leaving gaps for an agent to infer.

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 four short sentences, front-loaded with the core purpose, and every sentence adds meaningful content: the action, the dry_run default, the confirmation requirement, and the credential guarantee. There is no fluff or redundancy, 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?

The description is sufficient for a simple create operation. The output schema (present but not shown) likely covers return details, so the description need not explain them. It covers the critical safety behavior (dry_run) and credential handling. Missing error handling and edge cases, but given the existence of an output schema and the simplicity of the tool, it is reasonably 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 meaning. It adds value for the dry_run parameter by explaining its default and the condition for setting it false, but it says nothing about owner, repo, title, body, or labels. While some names are self-explanatory, the description does not fully cover the parameter semantics expected at 0% coverage.

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

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

The description clearly states the tool's action ('Create') and resource ('GitHub issue'), making it unambiguous and distinct from sibling tools like github_list_issues, which focuses on listing. The statement is direct and sufficient for an agent to understand what the tool does.

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 usage guidance, particularly around the dry_run parameter: it defaults to true and instructs to set it false only upon explicit user confirmation. This is a clear when-to-use rule. While it does not explicitly name alternatives or when not to use this tool, the distinction from listing issues is obvious from the purpose 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?

No annotations are provided, so the description carries the full burden. It discloses the required OPS_MCP_GITHUB_TOKEN and the returned fields (number, title, state, labels), which is useful. However, it does not mention pagination, rate limits, or the read-only nature explicitly, leaving some behavioral gaps.

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

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

Two sentences with no filler: the core action is front-loaded, followed by the operational prerequisite and a compact summary of the return fields. 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?

With an output schema present, return values need less explanation. The description provides the key prerequisite and filter behavior, but because parameter coverage is 0%, details like per_page pagination and state value options are left undocumented. This is adequate for a simple list tool but has clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate for the input schema's lack of field documentation. It only mentions 'state and labels' as filters, leaving owner, repo, and per_page without added meaning, and does not clarify accepted state values or labels formatting.

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 a specific verb and resource: 'List GitHub issues/PRs for a repo by state and labels.' It clearly distinguishes this tool from siblings like github_create_issue and github_pr_diff_summary by naming the listing behavior and the filter dimensions.

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 for when the tool is appropriate: when a repo's issues or PRs need to be listed by state and labels. It does not explicitly name alternatives or exclusions, but no sibling performs the same listing function, so the context is sufficient.

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

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

No annotations are provided, so the description must carry the burden. It mentions 'without full patches' but does not disclose potential rate limits, authentication requirements, or that the tool only returns metadata and not file contents. The behavior is partially transparent but incomplete.

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

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

The description is a single sentence that is concise and front-loaded with the main action. However, it lacks a period at the end, which is minor. It earns high marks for brevity but could add a second sentence for usage guidance.

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 output schema exists but its content is not shown, so the description must explain what the tool returns, but it only says 'summary' without specifying the format. Given that parameters are undocumented and no annotations exist, the description is insufficient for reliable invocation, especially for an API-specific 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% and the description provides no details about the parameters owner, repo, or pull_number beyond their names. The input schema only gives types and requiredness, with no descriptions, so an agent must guess what values are valid (e.g., pull_number is an integer but no range or format is given).

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

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

The description clearly states the function: summarizing a PR's changed files and diff stats without full patches. It distinguishes itself from tools that might fetch full diffs or list issues, though it does not explicitly name sibling 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 when to use it: when you need a summary rather than full patches. However, it does not explicitly contrast with sibling tools like github_list_issues or other code tools, so the usage context is inferred 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 behavioral disclosure burden and does state the key trait: it runs EXPLAIN without ANALYZE and without executing side effects. It omits details like connection/auth, but the safety-critical distinction is present.

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 filler. Every phrase contributes: the command variant, the query type, and the no-execution guarantee.

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 core behavior and no-side-effect guarantee are clear, and an output schema covers return values. However, because the schema has zero property descriptions, the optional params field is left completely unexplained, leaving a real completeness gap for a tool with two parameters.

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 explain both parameters. It only implies that sql holds a SELECT statement and says nothing about params, such as whether params supplies bind values for placeholders like $1 or how they are passed. This is a significant gap.

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 operation (EXPLAIN with FORMAT TEXT) and the target resource (a SELECT). It also differentiates itself from executing the query by explicitly noting no ANALYZE / executing side effects, so an agent can distinguish it from postgres_query_readonly.

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 'without ANALYZE / executing side effects' phrase gives clear context that this tool is for obtaining query plans rather than running the query. It does not explicitly name postgres_query_readonly as the execution alternative or list exclusions, but the intended use is evident.

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 so very well. It discloses the required environment variable, the fail-closed behavior, the rejection of DDL/DML and multi-statement SQL, and that this all happens before any connection is opened.

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

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

The description is short and front-loaded, with the core action in the first line. There is minor redundancy between 'DDL/DML rejected first' and 'write SQL fail closed', but overall every sentence contributes useful safety or setup 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?

The behavioral and safety aspects are well covered, and an output schema exists for return values. However, the tool has three parameters and zero schema descriptions, so the missing param semantics and row-limit behavior leave the definition merely adequate rather than 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 undocumented parameters. It only hints at parameterization without explaining the expected placeholder syntax, the shape of params, or the meaning of max_rows. This is a meaningful gap for an agent trying to call 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 names a specific verb and resource: 'Run a parameterized SELECT against Postgres', and explicitly states that DDL/DML are rejected. This clearly separates it from write tools and from the sibling postgres_explain, which is for EXPLAIN output rather than general read-only querying.

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 makes it clear this tool is for read-only SELECT queries and explicitly rejects DDL/DML, multi-statement, and write SQL. It does not name an alternative tool such as postgres_explain, so it misses the explicit 'use this when, use that when' comparison, but the boundaries are otherwise clear.

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