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

The readOnlyHint annotation is true, and the description aligns with that by noting the check operation. The description adds valuable behavioral context by stating the requirement for project context and the mutual exclusivity of the two parameters. It could have added more about what the output looks like or how drift is reported, but the annotation already covers the safety profile.

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, well-structured, and front-loaded with the core purpose. It then explains the two modes in a clear, logical sequence, followed by the constraint and prerequisite. Every sentence contributes essential 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?

Given that there is no output schema, the description could have been slightly more explicit about the return value (e.g., a list of drifted fields or a boolean). However, the description covers purpose, modes, constraints, and context requirements, which is sufficient for an agent to select and invoke the tool correctly in most 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 coverage is 100%, and the description reinforces the critical parameter semantics, especially the mutual exclusivity of testCaseId and specId and the meaning of checkAgainstLinkedVersion in single mode. The description adds interpretive value beyond the raw schema by clarifying the mode selection logic, which is the most important semantic aspect here.

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: checking for schema drift between a test case's linked endpoint snapshot and the current spec. It also distinguishes between two distinct modes (single test case vs. batch check for all linked test cases of a spec), which differentiates it from sibling tools like get_schema_drift_report or get_contract_drift.

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 explicitly explains the two modes and how to invoke each: provide testCaseId for single mode or specId for batch mode. It also clearly states the constraint that exactly one of testCaseId or specId must be provided, and notes that project context is required. This is excellent routing guidance relative to alternatives.

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's behavior is consistent with a read-only comparison. Beyond the annotation, the description discloses the two output modes and their size/behavior trade-off ('full returns the changed entities; flags returns only what changed and how'), plus the project-context prerequisite. This adds meaningful behavioral detail beyond what annotations provide.

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 purpose, the second covers the key optional parameter, and the third explains the detail modes and their trade-off. Purpose is front-loaded and there is no redundant repetition of schema or annotations.

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, the description adequately covers what the tool returns (added/removed/modified endpoints and schemas, changed entities vs flags). It also covers defaults, the optional parameter behavior, and the project-context prerequisite. For a read-only comparison tool of this complexity, nothing essential 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 100%, so the schema already documents all four parameters. The description goes further by explaining the semantic meaning of omitting sourceVersionId (compare against latest published) and the difference between 'full' and 'flags' for detail, which complements the schema's terse field descriptions.

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+resource: 'Compare two specification versions and show their differences: added/removed/modified endpoints and schemas.' This clearly identifies the tool's operation and output, and distinguishes it from siblings like list_versions (listing versions) and get_version (fetching a single version) 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 description gives concrete usage context: 'Omit sourceVersionId to compare against the latest published version' and explains when to choose detail 'full' vs 'flags' with the guidance that 'flags' is 'enough to decide where to look.' It also states the prerequisite 'Requires project context.' It does not explicitly name alternatives or exclusion conditions, so it stops 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?

The description mentions a side effect (sends a tools/list_changed notification) and notes that clients ignoring it can still call hidden tools directly, which is transparent. However, the annotation readOnlyHint: true directly contradicts the tool's mutation behavior (enabling is a state-changing operation). This inconsistency significantly undermines transparency, as an agent might incorrectly assume the tool has no side effects. The contradiction is severe enough to warrant a score of 1.

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, consisting of two sentences that cover the action, the mechanism, and the side effect. It is well-structured, with the core purpose first, followed by usage detail and a note about notifications. There is no unnecessary fluff, making it easy for an agent to parse quickly.

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 single parameter and no output schema, so the description doesn't need to explain return values. It provides the essential context: what the tool does, how to pass the argument, and what side effects (notification) occur. It could be slightly more explicit about the expected response (e.g., whether it returns a success indicator), but given the simplicity of the tool, the information is largely 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?

The input schema fully describes the single parameter 'names' as a comma-separated list of toolset slugs, which is clear and complete. The description repeats this information and adds a cross-reference to list_toolsets, but doesn't provide additional semantic depth beyond the schema. Since schema coverage is 100%, the baseline of 3 is appropriate; the description adds no extra value to the parameter explanation.

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: enabling one or more toolsets for the session so their tools appear in tools/list. It uses a specific verb ('Enable') and names the resource (toolsets), which is distinct from the sibling tool list_toolsets that merely lists available toolsets. The description also provides a direct reference to list_toolsets for finding slugs, removing any ambiguity about 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 explains when to use the tool: to activate toolsets so their tools become available in the session. It implicitly indicates that the tool is the action counterpart to list_toolsets, guiding the user to first list toolsets and then enable the desired ones. However, it doesn't explicitly state prerequisites (e.g., that the tool must be called before using tools from the enabled toolset) or mention that this is the only way to enable toolsets, but the 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?

Annotations already mark this as read-only, and the description adds useful behavior beyond that: the default status is open findings 'so the export reflects the current posture,' and project context is required. No contradictions or hidden side effects are apparent.

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, front-loaded with the core action and resource, and every sentence adds value: format, intended consumers, default behavior, and prerequisite context. No filler or redundant restating of the title.

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 single-optional-parameter export tool with readOnlyHint and full schema coverage, the description is complete: it identifies the output format, the scope, the default filter, and the required context. No output schema exists, but the SARIF document nature is stated directly.

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 already fully documents the single optional 'status' parameter with valid values and its 'open' default. The description adds no parameter-specific meaning beyond restating that default, so it does not exceed the baseline for full 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 clearly states the verb ('Export'), the resource ('the active project's security findings'), and the output format (SARIF 2.1.0). It also explains the tool's purpose for CI ingestion, which distinguishes it from other security-finding tools like get_security_findings.

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: the tool exports security findings as SARIF, defaults to open findings, and requires project context. It does not explicitly name alternatives or exclusion conditions, but the intended use for SARIF consumers 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?

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds valuable behavioral context by naming the supported formats and the project-context requirement, but it does not clarify how the exported content is returned (e.g., inline text, file artifact, download URL). With no output schema, a bit more behavioral detail would have been helpful.

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 states the core purpose and the key requirement without filler. Every phrase 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 two-parameter, read-only export tool, the description covers the operation, supported formats, and a necessary precondition. It does not describe the return payload, which would have been useful given there is no output schema, but the definition is still adequate for 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?

Schema description coverage is 100%, so the schema already documents both parameters and the format enum/default. The description reinforces the mapping between formats and the format parameter but adds no new semantics beyond what the schema provides. A 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 uses a specific verb ('Export'), identifies the resource ('API specification'), and specifies the exact output formats (OpenAPI YAML, JSON, Postman Collection). This clearly distinguishes it from sibling export tools like export_variables and export_findings_sarif.

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 clear prerequisite: 'Requires project context.' This tells an agent the tool cannot be used without an active project context. It stops short of naming alternative tools or explicit when-not-to-use conditions, but for a simple export operation the context requirement is valuable and clear.

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 meaningful behavior beyond that: it states that the report content is returned inline. It also discloses the project-context requirement, which is relevant for invocation. It does not describe failure modes or what happens if context is missing, but for a read-only export this is adequate.

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 three sentences with no wasted words. It front-loads the core action, then gives format details, usage guidance, return behavior, and a prerequisite. 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?

For a two-parameter read-only export tool, the description is complete: it specifies the resource, the format options with a recommendation, the inline return behavior, and the project-context requirement. The schema covers all parameter details, and no output schema exists, so the description's statement about inline content 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 coverage is 100%, so the schema already documents both parameters. The description adds value by explaining the practical purpose of the junit format for CI systems, which goes beyond the schema's simple value list. It also reinforces the format defaults, though it does not add new meaning for testRunId beyond the schema's 'Public Id (Guid)' 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 states a specific verb and resource: 'Export a test run as a report.' It distinguishes the tool from siblings like export_spec and export_findings_sarif by naming the test-run resource and from get_test_run by framing it as a report export. The format options further clarify what kind of output the tool produces.

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 explicit format-selection guidance: 'use junit for CI systems that consume JUnit XML.' It also notes that project context is required, which is a helpful prerequisite. It does not explicitly name alternatives or when not to use this tool, but the guidance provided is clear enough for the main decision points.

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 adds important behavioral detail beyond the readOnlyHint annotation: secret values are ALWAYS masked and there is no MCP path to decrypted secrets. This prevents an agent from expecting plaintext secrets and clarifies a significant limitation of the tool.

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 core behavior, the critical masking limitation, and the intended downstream use. The most important operational constraint (masking) is placed prominently and no filler is present.

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 read-only export tool with fully documented parameters, the description is complete. It tells the agent what the output looks like, what is masked, and how the output can be used, so no critical context is missing even without an output schema.

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 already documents all three parameters with 100% coverage, including format defaults and project/environment IDs. The description reinforces the format concept but does not add meaningful parameter-level detail beyond what the schema already provides, 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 identifies a specific verb and resource: exporting an environment's variables as .env or JSON text. It distinguishes itself from siblings like get_environment_variables by emphasizing the serialized output format and the masking behavior, which makes the tool's 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 gives clear usage context: the output is meant for review and for feeding back into import_variables, and it explicitly directs users to the web app when real secret values are needed. It does not explicitly name alternative MCP tools such as get_environment_variables or resolve_variables, so it stops short of a full when-to-use versus alternatives comparison.

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, so the safety profile is covered. The description adds useful behavioral context by stating it returns Markdown and requires project context, but it does not explain what count_project_context means or what happens if it 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?

Two concise sentences, with the primary action front-loaded and the return format and prerequisite stated directly. Every sentence earns its place without unnecessary elaboration 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 tool is simple with only two well-defined parameters and a read-only annotation, but the lack of an output schema means the description should clarify more about the changelog structure and the meaning of 'project context'. It is adequate for basic invocation but has notable gaps around prerequisites and return details.

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 documents specId and versionId as GUIDs. The description adds only implicit meaning by referring to 'specification version' and 'previous version', but it does not materially enhance parameter understanding 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 states a specific verb ('Generate'), a resource ('changelog for a specification version'), and the method ('by comparing it with the previous version'). It also distinguishes the output as structured Markdown, which separates it from sibling tools like compare_versions that would provide raw comparison data.

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

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

No explicit guidance on when to use this tool versus alternatives such as compare_versions. The phrase 'Requires project context' hints at a prerequisite but does not explain how to establish it or when this tool should be preferred over 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds value by stating the project-context prerequisite and specifying what the response includes (full rule set and scope count), which is useful since there is no output schema. Failure modes are not covered, but this is minor for a simple read tool.

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 sentence with no wasted words. The verb, resource, key output details, and precondition are all included concisely and in a sensible order.

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 operation, the description is complete: it names the resource, the distinguishing output, and the required context. The schema covers the parameter source, so nothing essential 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 coverage is 100% and the policyId parameter is already well documented in the schema as a GUID from list_alert_policies. The description adds no additional parameter meaning, so the baseline of 3 applies.

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 and resource: 'Get one alert policy' with its 'full rule set' and scope count. This clearly distinguishes it from list_alert_policies and other policy-related 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 makes clear this is for retrieving a single alert policy with full detail, and adds the prerequisite 'Requires project context.' It does not explicitly name alternatives or exclusions, so it stops 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?

The readOnlyHint annotation already signals this is a safe read, and the description adds meaningful behavioral context: pagination, newest-first ordering, full-organization scope without filters, and the need for organization context. It does not detail response field shapes, but that is not necessary at this level.

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, front-loaded with purpose, followed by scoping guidance and key behavioral caveats. Every sentence contributes actionable information with no redundancy or 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 9-parameter optional-filter tool with no output schema, the description covers the main usage scenario, pagination, ordering, and organizational context. It could mention response shape more explicitly, but the description already conveys what the log reveals well enough for an agent to use 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 schema already documents every parameter. The description adds useful context around the entityId filter and the unfiltered pagination behavior, but it does not significantly enrich the semantics of the other parameters.

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

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

The description clearly identifies a specific operation ('Read the API design audit log') and explains what the log contains: who changed what, when, and the actor type. This distinguishes it from sibling tools like get_request_logs or get_publish_history by focusing on audit history with entity filtering.

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 gives explicit practical guidance: filter by entityId before modifying something you didn't write, and notes the unfiltered behavior returns the whole organization history. It does not name alternative tools or state when not to use it, so it stops 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?

The readOnlyHint annotation already indicates no side effects, and the description adds that the tool is a read operation for merge trust and rebase preview. No contradictions exist.

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 focused and mostly concise, though phrases like 'that is the read to trust before merging' add a bit of marketing tone without much technical substance.

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 main outputs and optional behaviors, and the schema fully documents parameters. It omits error conditions or output schema details, but no output schema is provided and the tool's purpose 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 coverage is 100%, and the description enriches the boolean parameters by explaining what includeDiff and includeRebasePreview return. specId and branchId are clearly defined 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 states the tool retrieves a branch with counts of endpoints, schemas, and folders, and optionally includes diff and rebase preview data. This distinguishes it from list_branches and related merge/compare 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 explains when to use the diff ('read to trust before merging') and rebase preview options, and notes that project context is required. It does not explicitly contrast with sibling tools like get_merge_request, but the usage hints are strong 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?

Annotations already declare readOnlyHint=true, so the safe-read nature is covered without needing restatement. The description adds useful context by stating the output categories and migration hints, as well as the project-context requirement. It omits minor details like optional inputs or permission needs, but those are less critical given the read-only 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 two short sentences with no filler. It leads with the action, immediately describes the result categories, and ends with the prerequisite. 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 no output schema, the description wisely states the return shape: changes classified as Breaking, NonBreaking, or Deprecated with migration hints. It also covers the project-context prerequisite, and all three required parameters are documented in the schema. Minor gaps around the meaning of project context or behavior when there are no changes prevent a perfect score.

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 provides 100% coverage, documenting each parameter as a public GUID for the spec, source version, and target version. The description's phrase 'between two specification versions' aligns with the schema but does not add new format, default, or relationship semantics beyond what the schema already states. Therefore the baseline of 3 applies.

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+resource: identify and classify breaking changes between two specification versions. It also explains the classification categories (Breaking, NonBreaking, Deprecated) and migration hints. However, it does not explicitly distinguish itself from siblings like compare_versions or get_contract_drift, so it falls 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?

The description makes the core use case obvious and includes the prerequisite 'Requires project context.' It does not say when to prefer this tool over compare_versions, get_contract_drift, or generate_changelog, and it names no alternatives or exclusions. This provides only implied usage guidance beyond the prerequisite.

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, so the safe-read nature is covered. The description adds value by disclosing that the tool is for live polling, can be called repeatedly, and is not intended for completed runs. This goes beyond what annotations express.

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 compact sentences cover what the tool returns, when to use it, and what context is required. 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 single-parameter read-only polling tool, the description is complete: it names the inputs implicitly via the schema, lists the returned information, distinguishes the sibling tool, and notes the project-context prerequisite. The absence of an output schema is acceptable because the description enumerates the key response fields.

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%, and the single parameter testRunId is already documented as 'Public Id (Guid) of the test run'. The description does not add further parameter-level semantics, so the 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 starts with a specific verb and resource: 'Poll the live progress of a test run', then enumerates the exact data returned. It also explicitly contrasts itself with get_test_run, so an agent can distinguish this live-status tool from the finished-run 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?

It gives clear when-to-use guidance: 'Meant for watching a run that is still going; use get_test_run once it has finished.' It also states the prerequisite that project context is required, which is important operational guidance.

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?

Beyond the readOnlyHint annotation, the description discloses response limits (first 4 KB) and redaction of credential headers, providing useful behavioral context. It 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 concise, using two sentences to convey the output, usage workflow, and prerequisites. No unnecessary words 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?

Given the simple parameter set and absence of an output schema, the description sufficiently explains what the tool returns and how to obtain the needed ID. It covers the essential context for a read 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?

Both parameters have complete descriptions in the schema, so the baseline is 3. The tool description adds 'Requires project context,' but this is already implied by the projectId parameter's default-to-session 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 clearly states the tool's purpose: retrieving a single contract drift event with full details including per-field deviations, the actual value, route, request, and response body. It also differentiates from the list operation by emphasizing 'one event in full.'

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 explicitly states that IDs come from list_contract_drift, establishing a clear workflow prerequisite. The note 'Requires project context' also informs when the tool can be used.

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 mark this as read-only, so the description does not need to restate safety. It adds a useful behavioral note about requiring project context and describes the kind of summary returned, but it does not disclose potential error conditions, data freshness, or how the summary is computed.

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, stating the core purpose in the first sentence and then adding the key output metrics and the project context requirement. Every sentence earns its place with 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 read-only summary tool with one well-documented parameter and no output schema, the description adequately conveys what the call returns. It could be more complete by stating the format or granularity of the coverage summary, but the current content is sufficient for basic correct 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 already fully describes the single parameter as 'Public ID (GUID) of the test suite' with 100% coverage. The description references the test suite but does not add meaning beyond the schema, so the baseline of 3 applies.

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 operation: getting a contract test coverage summary for a test suite, listing the key metrics returned. It is distinct enough from siblings like get_contract_drift or get_test_suite, though it does not explicitly name or contrast any sibling.

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 only usage guidance is 'Requires project context,' which is a prerequisite rather than guidance on when to choose this tool over alternatives. It does not explain when to use this versus get_contract_drift, get_schema_drift_report, or get_test_results.

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 annotations already declare readOnlyHint=true, and the description reinforces this by explicitly stating the tool is read-only and that roles, members, teams, and SSO are intentionally not modifiable through MCP. This adds meaningful behavioral context beyond the annotations, though it does not discuss return format or errors.

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, front-loads the core purpose, and every sentence contributes either to understanding the return value, locating the parameter, or clarifying behavioral constraints. No filler 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?

For a single-parameter read operation with a fully documented schema and readOnlyHint annotation, the description provides enough information to invoke the tool correctly: what it returns, where the ID comes from, and the required context. No output schema exists, but the description compensates by listing key return fields.

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 fully describes roleId as the public ID (GUID) with 100% coverage. The description goes further by explaining where to obtain the ID, which adds practical meaning beyond the raw schema definition.

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 ('Get one custom role by ID') and the specific resource, then enumerates exactly what information is returned: permission strings, member count, and last-changed time. This distinguishes it from the sibling list_custom_roles, which retrieves multiple roles.

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 on how to obtain the required roleId, pointing to list_custom_roles and a member's customRoleId, and notes the required organization context. It does not explicitly contrast with list_custom_roles, but the ID-sourcing instruction implies the appropriate alternative usage.

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, so the safety profile is covered. The description adds behavioral context beyond that by specifying that the tool depends on the currently active project context and enumerates what statistics it returns. No contradiction with annotations exists.

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 concise sentences. The first states the tool's purpose and output, and the second gives the prerequisite. There is no redundant wording or repetition of the tool name.

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 parameterless read-only tool with no output schema, the description adequately names the returned information and the required setup. 'Project info' is somewhat vague, but the overall usage context is complete enough for an agent to correctly select and invoke the tool.

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

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

The input schema has zero parameters, so there is no parameter detail for the description to add. However, the description usefully clarifies that the effective scope is the 'active project' and that this is established by set_context, which is more informative than the empty schema alone.

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 ('get') and resource ('dashboard statistics') and lists concrete contents: spec count, environment count, and project info. It is clearly distinct from sibling tools like list_projects or get_project because it refers to an aggregate dashboard for the active project.

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

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

The description provides a clear precondition: the active project context must already be set, and explicitly instructs to call set_context first. It gives useful context for when the tool can be used, though it does not explicitly mention when not to use it or name alternative 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?

Annotations already declare readOnlyHint=true; the description adds real behavioral detail beyond that: it returns null when nothing is deprecated, and includeUsage surfaces recent traffic and top consumers. This shapes caller expectations about both the null case and the optional enrichment. No contradiction with the read-only 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?

Three sentences, front-loaded with the core purpose; each sentence contributes purpose, null behavior, usage flag, and prerequisite. No filler, though the second sentence packs the usage guidance into a slightly dense parenthetical style.

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, the description compensates by naming the returned fields (phase, sunset date, successor, migration guide) and the null case. The entityType values are covered by the schema, and the readOnly annotation covers safety. It remains silent on project-context failure behavior, but nothing essential is missing for a read-only single-entity lookup.

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 documents all five parameters with descriptions and defaults. The description adds only marginal semantic value — framing includeUsage as a pre-retirement decision check — while usageDaysBack and the GUID fields are left entirely to 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 states a specific verb and resource ('Get the deprecation plan of one endpoint or published version') with a clear scope, and itemizes the payload (phase, sunset date, successor, migration guide). It is clearly scoped to a single entity, which implicitly distinguishes it from list_deprecations, but it never names that or get_deprecation_policy as siblings.

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 actionable context: 'Set includeUsage to also see whether anyone still calls it — do that before retiring' tells the agent when the flag matters, and 'Requires project context' states a necessary precondition. It does not, however, state when NOT to use this tool or name alternative tools for listing many deprecations.

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's 'Get' verb aligns with that without contradiction. The description adds useful behavioral context beyond annotations: it specifies that organization context is required and enumerates what policy aspects the response covers, which helps an agent anticipate the result. No destructive or side-effect behavior is implied.

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 three sentences with no filler. It front-loads the primary action and resource, then gives a compact list of returned fields, and ends with a meaningful precondition. Every sentence contributes 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 simple zero-parameter, read-only getter with no output schema, the description is adequately complete. It names the resource, describes the returned policy components, connects the tool to the creation flow where it matters, and states the organizational context requirement.

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 zero parameters and schema description coverage is 100%, so there are no parameter semantics to document. The baseline of 4 for zero-parameter tools applies, and the description does not need to compensate for any schema 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 uses a specific verb ('Get') and a clear resource ('the organization's deprecation policy') and enumerates the exact contents returned: minimum grace period, migration guide requirements, successor/approval requirements, and reminder schedule. This makes it clearly distinct from related tools like get_deprecation_plan or list_deprecations by focusing on the organizational policy rather than individual plans.

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: this tool returns the organizational policy that governs deprecation plan creation, and it explicitly connects to manage_deprecation_plan('create') as the process being checked against. It also notes that organization context is required. It does not explicitly enumerate when not to use it or name sibling alternatives, so it stops 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond the annotation: the stateful set_context prerequisite and what the response contains (full content, metadata, timestamps). No contradiction with 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?

Three short sentences, each earning its place: purpose, return fields, and prerequisite. Front-loaded with the action and zero 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?

For a read-only fetch tool with no output schema, the description covers the essentials: what is returned and the critical set_context prerequisite. It does not describe error behavior when context is missing or the relationship/validation between the three IDs, but nothing an agent needs to invoke it correctly is fundamentally absent.

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% - each parameter already has a clear description ('The public Id (Guid) of the ...'). The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies. It could have noted the hierarchy among documentationId, versionId, and pageId, but the schema adequately identifies each parameter.

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 ('Get') and resource ('documentation page') and further clarifies by listing return fields (title, slug, Markdown content, page type, timestamps). This implicitly distinguishes it from siblings like get_doc_tree or get_doc_page_revision, though it never explicitly names an alternative.

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 clear, actionable prerequisite: 'Requires project context (call set_context first).' This tells the agent the ordering dependency, which is valuable. However, it does not state when NOT to use this tool or mention alternatives.

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 non-obvious behavioral context: it is a read-only preview of a revision before restoration, and it requires project context to be active. This goes beyond the annotation without contradicting it.

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 short sentences, each earning its place: what the tool returns, why to use it, and how to obtain the required revisionId. 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 simple read-only single-revision fetch, the description covers the return content, the workflow purpose, the source of the revisionId, and the project-context prerequisite. No critical information 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 100%, so the schema already explains each GUID parameter. The description adds one useful pointer — 'Get revisionId from list_doc_page_revisions' — but does not need to do more because the schema carries the parameter semantics.

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 and resource: 'Get one revision's full title and content'. It also frames the tool as 'the preview before restoring', which distinguishes it from generic doc-page getters and clarifies its role in the revision workflow.

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 concrete usage guidance: use it before restore_revision, get the revisionId from list_doc_page_revisions, and ensure project context is set. This tells an agent exactly when and how to invoke the tool in the surrounding workflow.

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 mark it read-only. The description adds value beyond that by listing exactly which settings are returned, mentioning the rowVersion dependency, and stating the project-context precondition. No contradictions or hidden side effects are apparent.

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 compact sentences front-load the purpose, enumerate the returned settings, and add the relevant update_doc_settings dependency. Every sentence contributes meaningfully 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?

For a single-parameter read-only tool with no output schema, the description adequately covers what the call returns and why it is needed. The only minor gap is not explaining how 'project context' is established, but that appears to be a platform-level convention.

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%, with documentationId already documented as 'The public Id (Guid) of the documentation'. The description adds no parameter-level detail, so the 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?

States a specific verb and resource: 'Get a documentation's settings', and enumerates distinctive content (version numbering scheme, publishing approval, code languages, schema name display). This clearly distinguishes it from doc tree/page/snippet tools and even ties it to update_doc_settings.

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?

Provides useful usage context: it requires project context and explicitly notes that it returns the rowVersion consumed by update_doc_settings. It does not explicitly say 'use this instead of X', but the enumerated settings make its role and timing clear.

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 adds context beyond the readOnlyHint by explicitly calling out that includeUsages is useful before deletion, signaling that this read operation can inform a destructive workflow. It also states a requirement ('Requires project context'), which helps set expectations about invocation prerequisites. There is no contradiction with readOnlyHint=true.

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 informative sentences, front-loaded with the core result ('full Markdown content and rowVersion') and the key usage caveat. The deletion advice is actionable and compact. It could slightly improve structure by separating the context requirement, but it is still 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 read tool with 3 required IDs and one optional flag, the description covers the critical behavioral clue (includeUsages before deletion) and the project-context requirement. There is no output schema, but the description does state that the response includes full Markdown content and rowVersion, so the agent knows the primary return shape. It doesn't explain how to get the required IDs, but that is a minor gap for this kind of docs snippet 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 input schema already covers all 4 parameters with descriptions, so the baseline is 3. The description adds extra value by clarifying that includeUsages also lists embedding pages and advises doing that before deletion, which goes beyond the schema's 'Also list the pages using this snippet.' It does not describe the snippetId/versionId/documentationId relationship, but the schema already names them clearly.

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: fetching one snippet with its full Markdown content and rowVersion. It also mentions an optional flag, includeUsages, to list embedding pages. It doesn't explicitly distinguish it from list_doc_snippets in the same sentence, but the singular 'one snippet' and the focus on full Markdown content and rowVersion clarify its core purpose.

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 'set includeUsages to also list the pages embedding it — do that before deleting one' gives a specific pre-deletion usage hint, and 'Need project context' implies when it can be called. However, it doesn't explicitly say when to use this tool over list_doc_snippets or get_doc_page, nor does it state when not to use it.

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 include readOnlyHint=true, and the description adds meaningful context beyond that: the returned structure is hierarchical, includes sort order, and nodes are typed. It also discloses the prerequisite of project context. No contradiction with 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?

The description is three sentences, front-loads the main purpose, and every sentence adds useful information: what the tool returns, the structure details, and a prerequisite. There is no redundancy or 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?

With no output schema, the description compensates by describing the hierarchical return type, sort order, node types, and required project context. It is reasonably complete for a read-only tree-fetching tool, though some details about node fields or error cases are not covered.

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 already documents both parameters fully (100% coverage), including their types and purpose as public IDs. The description adds no additional parameter-level meaning, so the baseline of 3 applies.

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 and resource: getting the documentation tree for a specific version. It also names the node types (page, folder, specSnapshot) and the hierarchical structure, which clearly differentiates it from sibling tools like get_doc_page or list_folders.

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 clear prerequisite: project context must be set, and it explicitly points to set_context as the needed call. It does not mention when not to use this tool or compare it directly to alternatives, but the context is clear enough for an agent to infer appropriate use.

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 covers the safe-read nature. The description adds valuable behavioral detail by explaining what specific state is inspected and that the tool should be consulted before publishing or building. The 'Requires project context' note also sets expectations about a precondition, going 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 two sentences, front-loads the core outcome, and enumerates the key state categories without wordiness. Every sentence contributes useful information—what it checks, when to use it, and a prerequisite.

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 read-only state-check tool with no output schema, the description covers the purpose, the information returned, and the timing of use. The 'Requires project context' hint is somewhat underspecified (it doesn't explain how to establish context), but given the sibling set_context tool and the readOnlyHint annotation, this 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 100%, with both parameters fully described as public Ids. The description does not add any additional semantic nuance about the parameters beyond what the schema already provides. Per the calibration baseline, this is adequate but not exceptional.

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 tool's purpose: checking whether a documentation version is ready to go live and whether the portal reflects current content. It enumerates the state dimensions (lifecycle, visibility, approval, edits since last build), making the tool's scope understandable. It doesn't explicitly name a sibling to differentiate from, but the focus on publish-state is distinct enough among the large sibling list.

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 usage context: 'Read this before publishing or building.' This tells an agent when the tool is appropriate. It also notes that project context is required, which is an important prerequisite. However, it does not explicitly state when not to use the tool or mention alternative tools such as get_publish_history.

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 is consistent with the description's 'Get' and 'fetch' language. The description adds behavioral nuance beyond the annotation by noting that multiple endpoints are returned 'in one call' with identical detail, and that endpointIds is used 'instead of' endpointId, clarifying the expected call semantics.

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 with no redundant wording. Every clause adds value: what info is returned, how to fetch multiple endpoints, the batch limit, and the environment prerequisite.

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 complete for an agent to decide and call the tool: it lists the returned content categories, the required project context, the batch behavior, and the parameter selection rule. No output schema is needed since the expected content is described directly.

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% and each parameter has a description that explains its role. The descriptions explicitly clarify the relationship between endpointId and endpointIds, including when to omit each, which fully conveys the parameter semantics.

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 ('Get') and resource ('endpoint'), enumerates the returned details (parameters, request body, responses, security schemes), and differentiates from siblings like list_endpoints and get_spec by emphasizing detailed per-endpoint information. The mention of fetching multiple endpoints via endpointIds further clarifies scope.

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?

Provides explicit when-to-use guidance by contrasting endpointIds with endpointId, specifies the maximum batch size (up to 25), and states the prerequisite ('Requires project context'). This leaves no ambiguity about when to call this tool versus alternatives.

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 mark the tool read-only, and the description adds non-obvious behavior: secret values are always masked and the sentinel {configured:false} is returned when no auth is configured. It also notes the organization-context requirement, which is not inferable from 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?

Three short sentences with the purpose front-loaded, followed by return behavior and a usage prerequisite. Each sentence carries distinct information and there is no redundant text.

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 getter with two parameters and annotations, the description is sufficient: it explains masking, the no-auth return shape, and the set_context prerequisite. Nothing needed to invoke correctly is missing, and no output schema is required to understand the return.

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%; both projectId and environmentId have meaningful descriptions. The tool description does not add parameter-specific details beyond the schema, so it makes no extra contribution to parameter understanding.

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 ('Get'), a specific resource ('environment-level authentication configuration'), and the owner ('an environment'). It is distinguishable from siblings like get_resolved_auth, though it does not 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?

It provides clear context by specifying the prerequisite: organization context via set_context. However, it does not explicitly exclude alternatives or state when to prefer this tool over others like get_resolved_auth.

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 useful behavioral context beyond that: it states the kind of information returned (version, frozen state, origin) and notes the project context requirement. This aligns with the read-only annotation and gives the agent a clearer picture of the tool's behavior without contradicting the structured metadata.

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 front-loads the action and resource, adds the distinct output fields, and notes the required prerequisite. Every part earns its place without redundancy or 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 one-parameter, read-only listing tool, the description covers the purpose, the key output fields, and the project context prerequisite. It does not spell out the return structure or define 'frozen' or 'pin' in more detail, but the schema and sibling context provide enough orientation 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 input schema fully describes specId as 'Public ID (GUID) of the API specification' with 100% coverage, so the parameter meaning is already documented in the schema. The description adds no further parameter-level semantics, which matches the baseline of 3 for fully covered schema descriptions.

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 ('List') and a specific resource ('which version each environment currently pins for this spec'), followed by the exact output attributes (frozen status, provenance). This clearly differentiates it from sibling tools like list_environments or get_environment_variables, which would be about listing environments or variables rather than pin states.

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 only usage guidance is 'Requires project context,' which communicates a prerequisite but does not explain when to prefer this tool over alternatives or when not to use it. It does not name any competing tool or exclusion condition, so usage is implied rather than explicitly directed.

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 safe read-only nature, and the description adds valuable behavioral details: variables are resolved, secret values are always masked, and organization context is required. This goes beyond the structured annotations, though it does not disclose permissions or failure 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?

Two short sentences deliver the core operation, a security-relevant behavior, and a context requirement 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 two-parameter read-only tool, the description covers the operation, masking behavior, and the organization context requirement, while the schema handles parameter semantics. The lack of an output schema leaves minor ambiguity about the return structure, but the description is largely complete for this simple use case.

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 projectId and environmentId are already well documented in the input schema. The description only reinforces the idea of a specific environment and resolved values without adding any new parameter-level detail.

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 operation ('Get'), the resource ('resolved variables'), and the target scope ('a specific environment'). It also adds useful security behavior about masking, but it does not explicitly differentiate this tool from related sibling tools like resolve_variables or export_variables.

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

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

No guidance is provided on when to use this tool versus alternatives such as resolve_variables, list_personal_variables, or get_environment_auth. The only stated condition, 'Requires organization context,' is a prerequisite rather than a usage rule, so an agent gets little help selecting between similar tools.

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

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

readOnlyHint already signals a safe read, and the description adds meaningful behavior beyond that: it reports per-environment aggregates, contract-test outcomes, spec versions, and pending cases. It also discloses the 'requires project context' precondition, which helps the agent set context before invoking.

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 compact sentences deliver the core purpose, the specific returned fields, the trustworthiness interpretation, and a required precondition 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 zero-parameter read-only tool, the description fully covers what data will be returned and what context is needed. Since there is no output schema, the description appropriately names the fields the agent should expect, and the readOnlyHint covers safety concerns.

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 zero parameters, so there is no parameter burden for the description to carry. The description handles this correctly by not inventing parameters, and the 'requires project context' note is a context-level clarification rather than a parameter requirement.

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 ('get') and resource ('environment verification'), and enumerates the exact data returned: last contract-test run time, result, spec version, and pending case count. The trustworthiness phrase further distinguishes it from general test-result or contract-drift 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 this tool: when you need environment-level verification status and trustworthiness of contract-test results. However, it does not explicitly state when not to use it or name alternative tools such as get_test_results or get_contract_drift.

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?

Even though readOnlyHint=true, the description importantly discloses that this read can spend AI budget, which annotations alone would not convey. It also explains the fallback to static guidance text and the 'source' field, giving the agent a clear mental model of non-obvious 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 compact but information-dense: every sentence contributes either to purpose, cost behavior, fallback semantics, or a precondition. It is front-loaded with the core action and output format, making it easy for an agent to parse quickly.

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 single-parameter read with no output schema, the description covers what the tool returns, the format, the source distinction, the budget implication, and the required context. Nothing essential for an agent to decide whether and how to invoke this tool 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 coverage is 100% and the single parameter findingId is already well documented as the Public Id from get_security_findings. The description adds little parameter-specific meaning beyond confirming the tool operates on a single finding, 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 names a specific verb and resource ('Get remediation advice for a single finding') and adds the output format (GitHub-flavored markdown). It distinguishes this tool from list-style reads like get_security_findings by emphasizing it targets one finding and can produce an AI-generated suggestion.

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, including the AI Assist budget condition and fallback behavior. It also explains why it is separate from other reads ('Unlike the other reads this one can spend AI budget') and notes the prerequisite of project context, though it does not name specific alternative 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?

Annotations already provide readOnlyHint=true, and the description adds a meaningful prerequisite: 'Requires project context.' It also discloses what the response will contain (raw source and normalized JSON), which goes beyond the schema and helps the agent anticipate the result.

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 sentence and front-loads the core action and resource. The only blemish is the unexplained 'E84:' prefix, which adds noise without helping an agent understand the tool.

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 single-parameter read-only tool with no output schema, the description is complete: it states what is retrieved, the identifier used, the content shape returned, and the project-context prerequisite. No critical information for invoking this tool 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 coverage is 100%, and the schema already documents fixtureId as the public GUID. The description adds little beyond restating 'public ID,' so it does not meaningfully expand parameter semantics.

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 ('Get'), a specific resource ('a fixture'), the identifier type ('public ID'), and the expected content ('raw source and normalized JSON content'). This clearly distinguishes it from sibling tools like list_fixtures or get_fixture_usage.

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: use this tool to retrieve a single fixture by its public ID, and project context must be set. It does not explicitly name alternatives or state when-not-to-use, but the singular-resource purpose is unambiguous enough for basic selection.

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 does not contradict that. The description adds useful behavioral context beyond annotations by stating the prerequisite 'Requires project context' and by disclosing what each view returns (referencing items vs saved versions with content).

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 three dense sentences with no filler: purpose, view-specific behavior, and a necessary prerequisite. The examples are concrete and the structure front-loads the main purpose before diving into 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?

With no output schema, the description carries the burden of explaining return values, and it does: 'used_by' returns referencing items and 'versions' returns saved versions with content. It also provides the prerequisite and use case. Minor gaps like pagination or error behavior are acceptable for a read-only inspection 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 100%, so the schema already documents both parameters. The description adds meaningful semantics to the 'view' parameter by explaining the default value and enumerating what 'used_by' contains (mock rules, test cases, seeds, doc examples), going beyond the schema's brief 'What to read'.

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 and resource ('Inspect a project fixture') and then enumerates exactly what the tool does via two views: 'used_by' lists referencing items and 'versions' lists saved versions with content. This clearly distinguishes it from siblings like get_fixture, which presumably returns the fixture itself.

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 usage context: the 'used_by' view is 'what to check before changing or deleting' a fixture. It also clarifies what each view is for. However, it does not explicitly name sibling alternatives or state when not to use this tool, so it falls short of a full 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?

The annotations declare readOnlyHint: true, but the description explicitly states that scope 'spec' writes a new snapshot, may raise alerts, and is not a free read. This is a direct contradiction between the described behavior and the annotation, which is a serious inconsistency for an agent relying on safety hints.

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 deliver all essential information: what the tool returns, the default scope, the per-spec behavior, and the context requirement. The format is front-loaded and every sentence carries meaningful content without 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?

Given the moderate complexity and the absence of an output schema, the description covers the main behavioral differences, side effects, and prerequisites. The only notable gap is that it doesn't explain what happens when project context is missing for scope 'spec', but overall it is sufficiently complete for correct 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 fully documents both parameters, so the baseline is 3. The description adds value by clarifying that specId triggers a live recalculation with side effects and that project context is required, going beyond the schema's simple 'required for spec' note.

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 'Get' and identifies the resource as a quality score, with clear scoping distinctions between org-level averaging and per-spec recalculation. It distinguishes itself from sibling tools like get_security_score by describing the aggregation behavior and breakdown output.

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 both scopes: org is the default and aggregates, while spec requires specId and carries side effects. It also states the project context prerequisite for scope 'spec', giving an agent actionable conditions for choosing the right invocation, though it does not explicitly name alternative 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?

Annotations already mark readOnlyHint=true, so the safety profile is covered. The description adds meaningful behavioral context: the returned data includes rowVersion, includeUsage behaves differently at spec vs project level, and the tool is positioned as a pre-deletion check. This is valuable 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 brief and front-loaded, with every sentence carrying distinct information. It avoids repeating schema details and packs the essential usage caveats into a compact form.

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, the description partially explains the return value by mentioning schema details and rowVersion. It also covers key prerequisites and level-specific behavior. It could be more explicit about response shape or possible errors, but it is sufficient for correct 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?

Schema coverage is 100%, so the baseline is 3. The description adds extra semantics by explaining that specId is needed for 'spec' level, that includeUsage lists references and is spec-only, and that project context is required. This exceeds baseline without replacing 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 states a specific verb and resource: "Get one header component with its schema details and rowVersion." It distinguishes itself from list-style siblings by emphasizing 'one' component and naming the component resource rather than policies or resolved headers.

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 operational guidance: choosing level 'spec' requires specId, includeUsage is spec-level only, and it should be used before deleting a component. It does not explicitly name alternative sibling tools like list_header_components, but the guidance is sufficient for correct invocation.

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, covering the safety profile. The description adds useful behavioral context about the cascade resolution and the project-context requirement. It does not describe error behavior or output format, but that is partially mitigated by the read-only 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 a single sentence with no filler. It front-loads the main action, then adds the cascade behavior and the prerequisite in a compact way.

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 getter with two fully documented parameters and no output schema, the description covers what is returned (resolved headers with cascade) and an important precondition (project context). It is reasonably complete, though it could mention what happens when project context is not set.

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 input schema already documents specId and endpointId. The description does not add parameter-level detail beyond referencing an endpoint and project context, which keeps this at the baseline for fully covered schemas.

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 and resource: 'Get resolved headers for an endpoint'. It adds detail about the full cascade (organization → project → specification). However, it does not explicitly differentiate this from sibling 'get_resolved_headers', so it is clear but lacks 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?

The description implies usage by saying 'Requires project context', which tells the agent a precondition. It does not state when to use this tool over alternatives such as list_header_policies or get_resolved_headers, so guidance is only 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?

The description aligns with the readOnlyHint annotation and adds behavioral details such as the spec-only constraint on includeImpact and the requirement for project context. It clearly communicates a read operation with no side effects or 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 concise and well-structured: it starts with the primary purpose, then explains parameters in a logical order, and includes a note on prerequisites. Each sentence contributes meaningful 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?

Given the absence of an output schema, the description sufficiently describes what the tool returns (scopes, components, rowVersion, and optionally impact). It also covers prerequisites (project context) and parameter-specific constraints, making it complete for an agent to decide when and how to invoke it.

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 full descriptions for all parameters (100% coverage). The description adds extra value by explaining the relationship between levels and specId, and by mentioning the spec-only limitation for includeImpact, which enhances understanding 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 action (get), the resource (one header policy), and the specific fields returned (scopes, assigned header components, rowVersion). It also distinguishes from sibling tools by emphasizing 'one' policy, aligning with the singular name versus plural alternatives like get_header_policies.

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 usage context by explaining the 'spec' vs 'project' levels, the need for specId, and the spec-only behavior of includeImpact. It also notes that project context is required. However, it does not explicitly compare with sibling tools (e.g., when to use this over list_header_policies), leaving some inference up to the agent.

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 only provide readOnlyHint=true. The description adds meaningful behavioral context beyond that: it returns null when the case is not linked, it requires project context, and it details exactly what the returned contract contains. This is strong disclosure for a read-only tool.

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 compact sentences front-load the core object and its contents, then deliver the use case, null edge case, and context requirement. Every sentence earns its place and there is no filler or repetition of structured fields.

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 one parameter, a read-only annotation, and no output schema, the description is complete enough: it explains what the returned contract contains, how to use it, what happens when there is no linked endpoint, and the project-context prerequisite. An agent has sufficient information to call and interpret the result 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 input schema already fully describes testCaseId as the public ID (GUID) of the test case, with 100% schema description coverage. The description reinforces the link between the test case and the endpoint contract but does not add meaningful parameter-level detail beyond what the schema provides.

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 precise verb and resource: 'Get the request contract of the spec endpoint a test case is linked to' and then enumerates the contract contents: header parameters, request body schema and example, and response schemas per status code. This clearly distinguishes it from generic endpoint, spec, and contract 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?

It explicitly states the intended use: 'use it to write assertions that match the contract instead of guessing.' It also frames the output as what the case is expected to send and receive. However, it does not name sibling tools or exclusion conditions, so it stops short of full routing guidance.

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 covers safety, and the description adds useful interpretation of the isDefault field, clarifying what it means when no policy was configured. No side effects are described, but none are expected for a read-only 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, front-loaded with the core purpose, and adds a meaningful clarification about isDefault without 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?

With no output schema, the description gives enough context about what the policy contains and the meaning of isDefault. It also notes the project context prerequisite. It could elaborate further on response shape, but the essentials are present.

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 fully describes the single parameter specId as 'Public ID (GUID) of the API specification.' The description adds little beyond the schema, but the 100% schema coverage keeps this at the baseline.

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 a specific action (get) and resource (merge policy of a spec), and describes what the policy includes (reviewers required and guards). This distinguishes it from sibling tools like get_merge_request and list_merge_requests.

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?

Provides a prerequisite by noting 'Requires project context,' which implies the agent must ensure a project context is set. However, it does not explicitly state when to use this tool versus alternatives or when not to use it.

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?

Beyond the readOnlyHint=true annotation, the description discloses the return composition (reviewers, decisions, comment thread), the cross-tool contract that reviewer userId values are what manage_merge_request('create') expects, the semantics of includeAuditTrail ('who-did-what history'), and the project-context prerequisite. All statements are consistent with the readOnlyHint annotation, so there is no 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?

Four short sentences, each earning its place: front-loaded purpose, the output cross-tool contract, the optional-parameter effect, the sibling alternative, and the prerequisite. There is no filler or repetition of the title, and the most decision-relevant scoping constraint comes first.

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 3-parameter, read-only tool with no output schema, the description covers what will be returned, what the optional parameter adds, the call prerequisite (project context), and the sibling to use when the diff is needed. Nothing an agent needs to invoke it correctly 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 100%, so specId, mergeRequestId, and includeAuditTrail are already fully documented. The description adds only mild color for includeAuditTrail ('who-did-what history of the spec's merge requests') beyond the schema's 'also return the audit trail', and nothing for the two required IDs. Baseline 3 is appropriate because the schema carries the parameter-documentation burden.

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 ('Get') and resource ('one merge request') and enumerates the exact contents returned: reviewers, their decisions, and the comment thread. The singular 'one' also differentiates it from list_merge_requests, and the closing sentence explicitly distinguishes it from get_branch, so an agent can disambiguate without opening either 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?

It explicitly names get_branch(includeDiff) as the alternative when the caller wants what the merge would actually change, and it warns that project context is required as a prerequisite. However, the when-not guidance is partial: it routes diff-seeking callers away but does not explicitly mention list_merge_requests for browse-all scenarios.

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

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

The description discloses the behavior of both views ('drift' compares against the latest spec version, 'state' returns the stored state) and notes it requires project context. The readOnlyHint annotation already covers the read-only nature, and the description does not contradict that. It could mention error cases or side effects, but none exist for a read-only inspection.

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 well-structured, with the primary action 'Inspect one mock rule' leading and the two view options explained compactly. Every sentence adds useful 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 description provides sufficient context for a simple read-only tool: it states the required project context, explains both view options, and indicates what each returns. There is no output schema, so the description's mention of 'lists what changed' and 'returns the stored state' gives a reasonable preview. It does not address error conditions or edge cases, but those are not essential for a basic inspection 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?

Both parameters (ruleId and view) are fully documented in the schema with clear descriptions: ruleId is the public GUID of the mock rule, and view specifies whether to inspect drift or state. The description reinforces the meaning of the view values, leaving no ambiguity.

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: 'Inspect one mock rule.' It distinguishes itself from sibling tools by specifying it operates on mock rules and offers two distinct views (drift and state), making its scope 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 explains what the tool does and mentions it requires project context, but it does not explicitly compare it to alternatives like list_mock_rules or get_mock_server. The guidance is implicit – a user would infer this is for inspecting a single mock rule – but not explicit about when to choose this over related 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?

Beyond the readOnlyHint annotation, the description discloses important behavior: it returns null when no mock server exists, never returns the access token, explains token regeneration invalidates the old token, and requires project context. These details inform the agent of edge cases and side-effect-free behavior without relying on 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?

The description is front-loaded with the main purpose and return value, then progressively adds optional behavior, security caveats, and prerequisites. Every sentence adds distinct useful information with no redundancy or 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?

Given the tool has no output schema, the description compensates by enumerating the returned fields, null behavior, optional stats behavior, token security semantics, and setup requirement. This is enough for an agent to call the tool correctly and interpret common results.

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

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

The input schema already documents includeStats with full coverage (100%), including its default and effect. The description restates this information in prose but adds minimal new semantic value, 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 clearly states the tool gets the mock server status and URL for the active project, names the returned fields, and differentiates itself from siblings like list_mock_rules or get_mock_usage by focusing on the mock server itself. It also specifies a null return when no server exists, which sharpens the purpose.

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: it requires project context via set_context first, and it directs users to create_mock_server when no server exists. It does not explicitly contrast with all similar mock-related tools, but the scoping to 'active project' and the create path provide strong usage guidance.

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?

ReadOnlyHint is already declared, and the description reinforces it with 'Read'. It adds meaningful behavioral detail beyond annotations: what each view returns (limit/reset date, monthly totals, per-project breakdown) and the requirement for organization context. No contradictions found.

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, front-loaded with the core purpose, then concise coverage of views and a practical trigger for use. Every sentence contributes 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?

For a read-only usage tool with two optional parameters and no output schema, the description covers the available views, the default behavior, the plan-limit context, and the organizational scope. Nothing essential is missing for correct 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?

Schema coverage is 100%, which sets the baseline at 3. The description adds value by explaining what each view value semantically produces, such as 'current' returning the limit and reset date and 'breakdown' returning the current month split by project. The months parameter is already well documented 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 uses a specific verb ('Read') and resource ('the organization's mock request usage against its plan limit'), and enumerates the three view variations. This clearly differentiates it from sibling tools like get_fixture_usage and get_session_usage, which target different usage 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?

Provides concrete usage context: 'This is what to check when mock requests start being rejected.' It does not explicitly list alternative tools or exclusion conditions, but the resource-specific scope and the rejection cue are strong enough guidance for an agent to select 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?

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds valuable behavioral context: it returns recent checks, lists the include flags' effects, and notes the project context requirement. It does not contradict annotations and provides extra detail about what gets fetched, earning a strong score.

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, with the core purpose front-loaded and the include flags explained succinctly. Every clause adds value, and it avoids redundancy with the schema. It is well-structured for quick parsing.

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 get tool with one required parameter and five optional booleans, the description is nearly complete. It states the return scope (monitor with recent checks) and the effect of each include flag, and notes the project context prerequisite. The absence of return-format details is acceptable given no output schema exists and the tool is straightforward.

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 every parameter is already documented. The description adds meaning by explaining that the include flags mirror the monitor detail page, which helps an agent understand their combined effect. However, this is contextual rather than essential, keeping it at the baseline of 3.

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 fetches a single monitor with its recent checks, using a specific verb and resource. It distinguishes itself from list_monitors (which lists all monitors) and list_monitor_checks (which likely focuses on checks alone) by framing the include flags as what the monitor detail page shows. The purpose is 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 implies usage for retrieving one monitor's details, and mentions the prerequisite 'Requires project context.' It does not explicitly name alternatives like list_monitors for bulk retrieval, but the context signals are clear enough for an agent to infer when to use this tool. The absence of explicit exclusions keeps it from 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?

Annotations already declare readOnlyHint=true, so the read-only behavior is covered. The description adds useful detail about which settings are returned and the project-context requirement, but it does not describe output shape, error behavior, or what happens when projectId is null. There is no contradiction with 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?

The description is a single compact sentence that front-loads the purpose, lists the specific settings returned, and ends with the context requirement. Every clause contributes information and there is 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?

This is a simple one-parameter, read-only getter with full schema coverage and no output schema. The description enumerates the returned settings and states the context requirement, so nothing critical is missing for correct 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 only parameter, projectId, is already fully documented in the schema with its type, default, and meaning. The description's reference to 'project context' reinforces but does not add new parameter semantics beyond what the schema provides.

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: 'Get the project's monitoring defaults' and enumerates exactly what is included (check history retention, default interval, timeout, incident threshold, schema validation mode, auto-creation). This clearly distinguishes it from sibling tools like get_monitor, list_monitors, and get_monitoring_sync_status.

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 indicates this tool is for project-level monitoring defaults and explicitly notes that project context is required. It does not name alternatives or state when not to use it, but the context is clear enough for an agent to select it appropriately.

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 declare readOnlyHint=true, and the description does not contradict that. It adds meaningful behavioral detail beyond the annotation by describing the comparison scope, the coverage assessment, orphan monitors, and drift-watched counts. It does not discuss pagination or output format, but the read-only nature is already covered.

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 first sentence front-loads the core purpose and the output dimensions, and the second sentence gives placement in the workflow. 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?

The description is strong for a read-only status tool: it explains what the comparison includes, the workflow position, and the project-context requirement. Since there is no output schema, a little more specificity about the exact return shape would make it fully complete, but the current level is highly usable.

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 documents all three parameters. The description adds context about 'one environment' and the project-context requirement, but does not add significant meaning beyond the schema's parameter descriptions.

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 ('Compare') and resource ('a spec against the monitors that exist for it in one environment'), then enumerates exactly what kinds of information the status conveys. This clearly distinguishes it from related tools like get_monitoring_settings or list_monitors.

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 an explicit usage context: 'The starting point before generating monitors' and the prerequisite 'Requires project context.' It does not name alternative tools or state when not to use it, but the context is specific enough to guide selection.

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?

Beyond the readOnlyHint annotation, the description discloses the custom-role resolution behavior, the organization-context prerequisite, and what read-only concretely means (members, roles, teams, SSO are not changeable via MCP and require the web app). Each of these adds behavioral context the annotation alone does not convey.

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?

Five sentences, each earning its place: purpose, use-case trigger, parameter guidance, precondition, and read-only scope. Front-loaded with the core function and free of filler or 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?

For a simple read-only tool with one optional parameter and no output schema, the description covers what is returned (role, effective permission strings, optional permission catalog), when to call it, the organization-context prerequisite, and the boundary of what it cannot do. Nothing an agent needs to invoke it correctly 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 coverage is 100%, so the baseline is 3. The description adds value beyond the schema by giving the parameter's purpose ('to map a denied action onto a name'), which explains why an agent would set includeCatalog rather than just what it does.

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+resource ('Get the caller's own role and effective permission strings in the active organization') with a distinguishing nuance ('custom roles resolved'). It clearly scopes to the caller's own permissions, which differentiates it from sibling tools like get_custom_role and list_members without needing to name them.

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?

Gives an explicit trigger condition ('This is the tool to reach for after a permission error'), an explicit precondition ('Requires organization context'), and an explicit when-not with an alternative ('members, roles, teams and SSO are not changeable through MCP by design — a human does those in the web app'). This fully routes the agent on when and when not to use it.

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 declare readOnlyHint=true, so the safety profile is already covered. The description adds value beyond that by explaining the isUserOverride semantics — that the response signals whether a category follows the org default or a personal override — and by flagging that organization context is required. It doesn't contradict the annotations, and the added behavioral context is meaningful for interpreting the result.

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 the core purpose front-loaded in the first clause and the scope nuances following. Every sentence carries distinct information — purpose, scope behavior, response interpretation, and a prerequisite — 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?

For a simple read-only tool with one optional parameter and no output schema, the description is complete: it states what is read, how each scope behaves, what a key response field means, and the context prerequisite. The agent has everything needed to decide whether and how to call this tool without further investigation.

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 with the schema already documenting the 'scope' parameter. The description earns an extra point by elaborating on what each scope value actually returns (own settings with isUserOverride interpretation vs. org defaults), adding behavioral meaning beyond the schema's brief 'Whose settings to read' phrasing.

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-resource pair — 'Read notification preferences per category' — which precisely states what the tool does. It further differentiates the two scope modes ('user' vs 'org'), making the purpose unambiguous and implicitly distinguishing it from the sibling write tool update_notification_preferences.

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, actionable guidance on which scope to select based on intent: 'user' for one's own settings, 'org' for organization defaults, plus the prerequisite that organization context is required. It does not explicitly name alternatives or when-not-to-use conditions, but the scope semantics effectively tell the agent how to invoke the tool correctly for each situation.

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 mark readOnlyHint=true, and the read-only 'Get' verb is consistent. The description adds useful behavioral context beyond annotations by specifying that the response includes the full content and rowVersion, giving the agent a clear expectation of the output surface.

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 with no filler. The verb, resource, and return contents are all front-loaded, making it immediately scannable for an agent.

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-only get operation, the description is nearly complete: it states what is returned (full content and rowVersion), and the schema handles parameter documentation. It lacks explicit error or edge-case behavior, but that is not critical for this straightforward 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?

The schema documents templateId with 100% coverage, so the description does not need to add parameter details. The description adds no extra meaning beyond what the schema already provides, 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 names a specific verb ('Get'), a precise resource ('one organization documentation template'), and the key return contents ('full content and rowVersion'). This clearly distinguishes it from sibling list_org_doc_templates and other get_* 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?

No explicit alternatives or 'when to use' guidance is provided. The wording 'one ... template' implies this tool is for retrieving a single template as opposed to listing them, but the description does not explicitly route the agent away from list_org_doc_templates.

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 readOnlyHint=true already declaring this as a safe read, the description adds useful behavior beyond annotations: it returns schema details and rowVersion, optional usage listing, and a meaningful precondition ('Requires project context'). It is consistent with the annotation and adds practical operational context.

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 carry all the essential information with no filler. The main purpose is front-loaded, and the optional parameter behavior plus prerequisite are compactly appended.

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 tool with complete schema coverage and a readOnly annotation, the description is sufficient: it names the returned data, explains the optional usage flag, and states a prerequisite. Nothing critical is missing for an agent to select and invoke this 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?

The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds extra semantic value by explaining the includeUsage parameter's effect and its recommended timing ('do that before deleting one'), which goes beyond the schema's simple default 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 states a specific verb ('get'), a specific resource ('one reusable parameter component'), and the key returned content ('schema details and rowVersion'). It clearly distinguishes itself from list_parameter_components and sibling get_*_component 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 provides clear usage context: use includeUsage to list referencing endpoints, and do so before deleting a component. It also notes the prerequisite of project context. It does not explicitly contrast with list_parameter_components, but the singular 'one' implies the appropriate use case.

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, so the read-only safety is covered. The description adds useful behavioral constraints beyond the annotation: only the latest published version is accessible and project context must be set beforehand.

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?

Four short sentences, each carrying distinct information: what the tool returns, scoping constraints, how to discover slugs, and the required precondition. No filler or restatement of 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?

For a simple two-parameter read tool with a high-coverage schema and a readOnly annotation, the description is complete: it names the return content, scopes the accessible pages, gives the discovery path, and states the prerequisite.

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 the baseline is 3. The description adds meaningful value by tying documentationId to the latest published version and by telling the agent to use search_portal_docs to discover valid pageSlug values.

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-resource statement: 'Retrieve a single PUBLISHED documentation page by slug, with its full Markdown content.' The qualifiers 'single', 'PUBLISHED', 'by slug', and 'latest published version' clearly separate it from discovery tools like search_portal_docs and from revision-oriented 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?

It explicitly tells the agent to use search_portal_docs to discover slugs and requires set_context first. It clearly states the call context but does not explicitly name when-not-to-use alternatives for other version/unpublished scenarios.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds behavioral context beyond the annotations: the set_context prerequisite and the active-project fallback behavior when projectId is omitted.

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 zero filler: the main purpose is front-loaded, followed by the prerequisite and the default argument behavior. 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?

For a single-optional-parameter getter with readOnlyHint=true and no output schema, the description covers purpose, the required precondition, and the parameter fallback — everything needed to call it correctly. The only minor gap is the lack of return-shape detail, which is acceptable for a simple getter without an output schema.

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%, with projectId already documented as an optional GUID defaulting to null. The description's parameter guidance largely restates the schema's 'If omitted, uses the active project context', so the schema carries the heavy lifting and the description adds little new 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 states a specific verb and resource — 'Get detailed information about a project' — and adds scope detail ('including its environments'). It is clear enough to distinguish from sibling list tools like list_projects, though it does not name any sibling explicitly.

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

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

The description gives a concrete prerequisite ('Requires organization context (call set_context first)') and documents the no-argument fallback ('If no projectId is given, uses the active project context'). However, it gives no explicit guidance on when to choose this tool over alternatives such as list_projects or get_branch.

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 establish readOnlyHint=true, and the description consistently describes a read-only listing operation, adding the contextual detail that project context is required. It does not go into pagination behavior, ordering, or empty-result semantics, but for a simple read-only tool the annotation covers the main safety concern.

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 immediately states the action and outputs, plus a short prerequisite clause. No filler; every word adds 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 simple listing tool with a fully described schema, the description tells the agent what data will be returned and what context must be established. With no output schema, a small explicit note about default ordering or pagination would make it fully complete, but the essentials are present.

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 already documents all four parameters with descriptions at 100% coverage, so the description does not need to repeat them. It adds no extra meaning about skip/take or GUID formats, so the baseline of 3 applies.

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 the verb 'List', identifies the resource ('a version was published'), and names the concrete data returned ('when', 'to which target', 'by whom'). This makes it easy to distinguish from siblings like get_version or get_scheduled_publishes without opening 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?

It states a clear prerequisite, 'Requires project context', which tells the agent that set_context must be called first. It does not, however, name alternatives or state when this tool should be preferred over similarly named publish/version tools, leaving that to inference.

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, so the read-only nature is covered. The description adds useful behavioral/return context: the tool returns inline schema or linked schemaId, rowVersion for update workflows, and optionally usage details. It also discloses the project-context prerequisite, with no contradiction to the 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?

Two compact sentences with no filler. The main purpose and return content are front-loaded, the optional behavior is stated second, and the prerequisite is separated clearly. Every sentence contributes 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?

With no output schema, the description appropriately explains the return values (schema definition, rowVersion, optional usage). It covers the required parameters indirectly and states the project-context prerequisite. Minor gaps remain around not-found/error behavior and how to establish project context, but the core calling information is present.

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 input schema already documents all three parameters clearly. The description does not add new parameter-level meaning beyond mentioning the optional usage details behavior, which is already in the includeUsage schema description. Baseline 3 applies.

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: 'Get a request body component' and goes beyond by detailing exactly what is returned—schema definition (inline schemaJson or linked schemaId) and rowVersion. This clearly distinguishes it from sibling list/get tools for other component types like get_response_component or get_parameter_component.

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 context: you need a single request body component's schema/rowVersion, and includeUsage is for when endpoint linkage details are needed. It also notes 'Requires project context.' However, it does not explicitly state when to prefer this over list_request_body_components or mention any exclusions/alternatives.

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. The description adds value beyond that by disclosing the null-return behavior when no request exists and the project-context requirement. These are genuine behavioral traits an agent needs to know. It doesn't cover response format details, but for a simple single-parameter read tool the null case is the key behavior and it is disclosed.

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

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

Three sentences with zero waste: the core purpose and return contents are front-loaded in sentence one, the null edge case and fallback tool in sentence two, and the context prerequisite in sentence three. 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?

For a tool with one required parameter, no output schema, and no nested objects, the description is complete: it states what is returned, enumerates the returned fields, discloses the null case, points to the corrective tool, and flags the context prerequisite. Nothing an agent needs to call it correctly 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 100% — the schema already documents testCaseId as 'Public Id (Guid) of the test case.' The description adds no parameter-specific meaning beyond the schema, so the baseline of 3 applies. The description's mention of the request configuration contents does not meaningfully clarify the single parameter.

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 and resource ('Get the full request configuration of a test case') and enumerates exactly what is returned: method, URL, body, scripts, and headers with their ids. This precise scoping clearly distinguishes it from siblings like get_request_logs or list_test_cases without needing to inspect their schemas.

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 explicit edge-case guidance: 'Returns null when the case has no request yet — use set_test_case_request to create one,' which names an alternative tool and the condition that selects it. It also states the prerequisite 'Requires project context.' It stops short of a broader when-to-use vs. when-not-to-use discussion across the large sibling set, hence not 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?

With readOnlyHint=true, the safety profile is already covered. The description adds useful behavioral details: the difference between list and single-log responses, full bodies/headers, and the need for project context. However, it claims support for 'time range' filtering, but no such parameter exists in the input schema, which is a misleading behavioral statement.

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-structured: purpose first, then filtering options, then the special logId case, then the prerequisite. Every sentence adds useful information, and nothing is redundant.

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 7-parameter tool with no output schema, the description covers the main decision points: what the tool returns, when to use logId, and the project-context prerequisite. It does not describe the response shape beyond 'list' vs 'full bodies and headers', but the schema covers pagination and filter semantics, so the description is mostly 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 the baseline is 3. The description adds meaningful context for logId, explaining that it returns full bodies and headers and that it is the parameter to use for wrong-rule diagnosis. It also clarifies the purpose of method/path/status filters, going slightly beyond raw schema descriptions. The unsupported 'time range' reference is a minor drawback.

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 ('get'), a resource ('request logs from the mock server'), and the content ('recent incoming requests and matched rules'). It also clearly differentiates the list mode from the single-log mode via logId, which distinguishes this tool from siblings like get_audit_log or get_mock_rule_diagnostics.

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 explicit usage guidance for logId: use it to get one full log when a request matched the wrong rule. It also provides a prerequisite ('Requires project context (call set_context first)'). However, it does not name alternative tools or state when not to use this tool, so the guidance stops short of full alternative routing.

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 only mark the tool as readOnly; the description adds meaningful behavior: secrets are not returned, inheritance resolution spans case/suite/environment/project, and project context is required. This goes beyond the annotation without contradicting it.

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 with no filler: purpose and scope first, then secret-handling warning, then use case and prerequisite. 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?

All invocation-relevant information is present: required params, optional environment, prerequisite, and what the result conveys. There is no output schema, but the description explains what is shown and what is redacted; exact return shape is not necessary 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?

Schema description coverage is 100%, so the schema already documents entityId, entityType, and environmentId. The description adds contextual framing about inheritance and project default but no new parameter-level detail, so 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?

Description uses a specific verb ('Show') and names a precise resource: the resolved auth for a test suite or test case after inheritance, including its source. This clearly distinguishes it from raw environment auth tools like get_environment_auth.

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?

Gives an explicit trigger: 'Use this before debugging a 401 by hand.' It also states a prerequisite ('Requires project context'). It does not explicitly name alternatives or say when not to use it, but the use case 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?

Annotations already set readOnlyHint=true, so the safety profile is covered. The description adds meaningful behavioral context: the resolution cascade (organization, project, spec policies, local overrides, exclusions) and that each header includes its source. This goes beyond the annotation and gives the agent a precise mental model of what the tool computes.

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, tightly packed with essential information: what it returns, how it differs from a sibling, and a prerequisite. No filler or repetition. The most critical scope detail 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 read-only tool with no output schema, the description sufficiently conveys what the result includes (headers with origin). It also handles the main disambiguation with get_header_policies and notes the project context requirement. Nothing critical is missing for correct 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?

Schema coverage is 100% and both parameters have descriptions, so the schema already documents the parameters. The description does not add extra meaning to the parameters themselves; it focuses on the output semantics. 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 specifies a clear action ('Get the headers that actually apply to one endpoint response'), the exact scope (one response after full cascade), and details what is returned (with origin). It explicitly distinguishes from the sibling get_header_policies, which covers a whole endpoint grouped by status code, so an agent can easily tell them apart.

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 explicitly names the alternative (get_header_policies) and the difference in scope (one response vs. whole endpoint), giving clear when-to-use guidance. It also states a prerequisite ('Requires project context'), which is useful operational guidance.

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 declares this as a read operation, and the description adds useful behavioral context: the response includes schema, headers, and rowVersion, and includeUsage optionally lists referencers. It does not contradict annotations and provides meaningful details beyond the structured fields.

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 concise sentences that front-load the action and resource, then add the optional usage and prerequisite. Every clause earns its place with no redundancy or 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 read-only tool with no output schema, the description sufficiently covers the return contents, the optional parameter behavior, and the required project context. Combined with full schema descriptions and the readOnlyHint annotation, an agent has what it needs to call 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 coverage is 100%, so the baseline is 3. The description adds value by explaining what the response contains and explicitly clarifying the includeUsage parameter's effect, which goes beyond the schema's brief descriptions.

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 and resource: 'Get one reusable response component' and explicitly names what is returned (schema, headers, rowVersion). The word 'one' distinguishes it from the sibling list_response_components, making the tool's scope clear.

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 only usage guidance is 'Requires project context,' which is a prerequisite but not a routing rule. It implies use when a specific componentId is known, but it never names alternatives like list_response_components or says 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?

Annotations already declare readOnlyHint and idempotenceHint, so the safety profile is covered. The description adds the pending-by-default filtering behavior and the project-context requirement, which are useful. Still, it does not mention return format, pagination, or other runtime behavior, so the added context is moderate but not rich.

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 fluff. The primary action is front-loaded, followed by the most relevant behavioral detail and a context requirement. Every clause 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 read-only filtered-list tool, the description covers required parameters, optional flags, defaults, and a context prerequisite. The absence of an output schema is not a major gap for invocation. Minor ambiguity remains around what 'project context' entails and how results are returned, but nothing essential to calling the tool correctly 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 coverage is 100%, so the baseline is 3. The description confirms that includeExecuted and includeCancelled control which schedules are shown and that pending is the default, but the schema already documents these defaults. No additional meaning is added for specId or versionId.

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

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

The description clearly states the verb and resource: 'List the scheduled publishes of a version.' It identifies the operation and its scope. It does not explicitly differentiate from sibling tools like get_publish_history or list_test_schedules, but 'scheduled publishes' is specific enough to avoid major ambiguity.

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

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

The description explains the default behavior ('Pending ones by default'), the optional flags for seeing other results, and a prerequisite ('Requires project context'). However, it does not say when to prefer this tool over alternatives or when not to use it, so 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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful context beyond the annotation: project context is required, and the response can optionally include endpoint usage details. It does not describe response format details or error behavior, but given annotation coverage, this is adequate.

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 purpose is front-loaded, the optional behavior follows naturally, and the prerequisite is stated clearly. Every clause 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 read-only get-by-ID tool, the description conveys what the tool returns (schema definition plus optional endpoint usage) and a key precondition (project context). The input schema covers the parameters. It could be more explicit about what 'requires project context' means operationally, but the description is sufficient for correct 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?

Schema description coverage is 100%, so the input schema fully documents specId, schemaId, and includeUsage. The description reinforces the meaning of the key parameters by mentioning the full JSON Schema definition and optional endpoint usage details, but it adds no information beyond the schema descriptions.

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 and resource: 'Get detailed information about a schema including its full JSON Schema definition.' This is clear and gives an agent a concrete sense of the return payload. However, it does not explicitly distinguish get_schema from sibling tools like get_shared_schema or list_schemas, so it stops short of full 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?

Usage is implied: an agent would call this when it needs a schema's full JSON Schema definition or endpoint usage details. The description also gives an explicit prerequisite with 'Requires project context.' It does not mention when to prefer alternatives such as list_schemas or get_shared_schema, so the guidance is only partially complete.

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