Routebase

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 meaningful detail about mode-specific behavior and the linked-version comparison option. It does not mention output format or error cases, but the read-only nature is well 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?

The description is concise and well-structured, using three sentences to cover purpose, modes, parameter constraints, and the related alternative. No redundant or vague wording 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?

The description gives enough context for tool selection and basic invocation, including mode constraints and the alternative tool. It does not describe the return value, which would be helpful given there is no output schema, but this is not critical for choosing 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 schema descriptions cover all three parameters well, and the description adds critical interaction semantics such as exactly-one-of and the single-mode-only behavior of checkAgainstLinkedVersion. This goes beyond the schema's basic field documentation.

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

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

The description clearly states the tool checks for schema drift between a test case's linked endpoint snapshot and the current spec. It also distinguishes two modes and contrasts with sync_test_from_spec, making its primary use obvious.

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, states that exactly one of testCaseId or specId must be provided, and notes the behavior of checkAgainstLinkedVersion. It also gives guidance on when to use sync_test_from_spec instead, providing clear usage direction.

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 read-only nature, and the description adds the useful prerequisite 'Requires project context.' It does not mention rate limits or auth, but for a read-only comparison tool with the annotation present, this is sufficient and non-contradictory.

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

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

The description is four sentences, each carrying essential information: the core action, the default behavior, the detail modes, and the relationship to the sibling tool. It is front-loaded with the main purpose and contains no redundant or filler content.

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

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

Given four parameters and no output schema, the description covers all necessary decision points: how to choose source and target versions, how to control output size, the requirement for project context, and the alternative tool for a written summary. An agent has enough information 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% (all four parameters have descriptions). The description reinforces the semantics of sourceVersionId (omit for latest) and detail ('full' vs 'flags') and adds the rationale that 'flags' is 'much smaller, and enough to decide where to look,' which goes beyond the schema text.

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 specific verb 'Compare two specification versions' and the resource ('specification versions'), and enumerates the kinds of differences shown (added/removed/modified endpoints and schemas). It also distinguishes itself from the sibling generate_changelog, making its purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: 'Use this for the raw structural difference' and contrasts it with generate_changelog for a written summary. It also explains how to omit sourceVersionId for the latest published version and describes the two detail modes with their trade-offs, leaving no ambiguity about when to invoke 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?

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?

The readOnlyHint annotation already covers the non-mutating nature, and the description adds useful context by specifying the output format, the default filter, and the requirement for project context. It does not explicitly state side effects, but the annotation and export-focused wording make the behavior reasonably clear.

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

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

The description is concise and well structured, with the main purpose stated first, followed by default behavior, use case, alternative tool, and prerequisite. Every sentence adds value and there is no fluff.

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

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

Given the tool's simplicity, the description covers all necessary context: what it produces, the format, the default behavior, when to use it, the alternative tool, and the required project context. No important 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?

The schema already describes the status parameter with possible values and default, so coverage is high. The description adds the rationale for the default ('Defaults to open findings so the export reflects the current posture'), which provides extra meaning beyond the 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 clearly states that the tool exports the project's security findings as a SARIF 2.1.0 document. It names the exact resource, action, and output format, leaving no ambiguity about the tool's 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 explicitly says to use this tool to hand findings to CI or GitHub and points to get_security_findings for reading findings in the product. It also notes the default open-findings behavior, giving clear guidance on when and how 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 indicate readOnlyHint: true, and the description adds 'Requires project context' as a prerequisite, providing extra behavioral context beyond the annotation without contradiction.

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

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

The description is concise, two sentences, front-loading the purpose and then providing usage guidance 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?

Given the simple tool with two well-documented parameters, the description and schema together fully cover the purpose, usage, and parameters, including the output format implication.

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 descriptions in the schema (specId and format with allowed values), so the description adds little beyond what the schema already covers, earning the baseline score.

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 exports an API specification in specific formats (OpenAPI YAML, JSON, Postman Collection), distinguishing it from other export tools and validation 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 provides when to use (to get the finished document) and points to validate_spec as an alternative for checking against the standard, aligning with the calibration example for a perfect usage score.

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

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

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 declare readOnlyHint=true, so the safety profile is covered. The description adds behavioral detail: it compares against the previous version and returns a Markdown changelog, which is beyond the annotation. No contradictions or hidden side effects are disclosed, but the added context is meaningful.

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

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

Two sentences with zero fluff. The purpose, return format, and routing to the sibling tool are all front-loaded, and the prerequisite is stated last. 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 read-only tool with two well-documented parameters and no output schema, the description explains the return type (Markdown) and the comparison basis. It does not detail the changelog's internal structure, but that is not critical for invocation. The 'requires project context' hint is a minor gap but acceptable.

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

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

Schema description coverage is 100%, so both parameters (specId and versionId) are already documented with their types and purposes. The description does not add any parameter-specific meaning beyond the schema, meeting the baseline of 3 for high 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 a specific verb (generate), resource (changelog for a specification version), and return type (Markdown). It also distinguishes itself from the sibling compare_versions by noting it provides a readable summary versus a raw structural diff, making it 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?

Explicitly instructs when to use this tool ('Use this for a readable summary of what changed') and names the alternative for the raw diff ('for the raw structural diff use compare_versions'). Also notes a prerequisite ('Requires project context'), giving agents clear decision criteria.

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 side-effect safety. The description adds useful behavioral detail about what is returned (full rule set, scope count) without contradicting 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?

Two concise sentences with no redundant information. The key guidance is front-loaded and the alternative tool is named clearly.

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 provides a reasonable idea of the return content (full rule set and scope count). It does not cover error behavior or response shape, but for a simple get-by-id fetch this 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?

The schema already documents policyId with a clear description. The description reinforces that it is the policy id and that it comes from list_alert_policies, and adds the project context requirement 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?

States a specific verb ('Get'), a specific resource ('one alert policy'), and the exact scope of the result ('full rule set and how many scopes it is assigned to'). It also explicitly distinguishes itself from list_alert_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?

Explicitly says when to use it ('when you already have the policy id') and when not to ('to browse a project's policies use list_alert_policies'), plus notes the project context requirement.

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?

The readOnlyHint annotation already covers side effects, and the description adds useful output context by stating that results are classified as Breaking, NonBreaking, or Deprecated with migration hints. It does not detail error behavior, but the read-only nature is clear and not contradicted.

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

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

The description is concise and front-loaded with the core purpose, followed by output context, usage direction, and a prerequisite. Every sentence adds 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?

The description provides enough context for selection and invocation: the purpose, the classification output, the alternative tool, and the project-context requirement. Since there is no output schema, the brief output description helps, though more detail on the exact response structure would improve completeness.

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 descriptions cover 100% of the parameters with clear meanings for specId, sourceVersionId, and targetVersionId. The tool description does not add significant extra parameter semantics 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 uses a specific verb ('Identify and classify') and clearly names the resource ('breaking changes between two specification versions'). It also distinguishes this tool from the sibling compare_versions by noting that this one returns classified breaking changes.

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?

Explicitly states when to use this tool ('Use this for classified breaking changes') and when not to ('for the full structural diff use compare_versions'). It also notes the prerequisite 'Requires project context,' giving clear selection 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?

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?

The readOnlyHint annotation covers safety, and the description adds behavioral detail about what is shown (test case linkage, schema drift, endpoint coverage). 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?

Two concise sentences with no redundant words. The key scope and alternative tool are clearly 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?

Given the output schema is not present, the description provides sufficient context about the return content and the selecting condition. No critical missing information.

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 testSuiteId is fully described in the schema, so the description adds no extra parameter meaning. 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?

Clearly states the verb 'Get' and specific resource 'contract test coverage summary for a test suite'. Differentiates from siblings like check_schema_drift by name and 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?

Explicitly instructs to use for a suite's coverage overview and directs to check_schema_drift for single-case drift. Also notes the prerequisite 'Requires project context'.

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 states the read-only nature in words and explains that plan, seat, and top-up changes are unavailable through MCP by design. It also discloses that includeHistory changes the response to include consumption per day and per feature, which is valuable behavioral 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?

Three sentences, front-loaded with the core purpose and result contents, followed by usage boundaries and an alternative. Every sentence adds information, and there is no filler or repetition 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?

With no output schema, the description carries the burden of explaining what the caller gets back, and it does: balance remaining, plan inclusions, rollover/top-ups, reset time, and optional historical usage. It also covers when to use the tool, the alternative, and the organization-context prerequisite, making it complete for a read-only balance query.

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 meaning by explaining that includeHistory controls the historical consumption view and by summarizing the returned categories. It does not deeply elaborate days/featureId beyond the schema, but the schema already documents those 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 states a specific verb and resource ('Get the AI credit balance') and enumerates exactly what the result covers: remaining credits, plan inclusions, rollover/top-ups, and reset timing. It also explicitly differentiates itself from the sibling get_usage_limits by scoping itself to AI credits only.

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 when-to-use guidance ('Use this for AI credits only') and names the alternative for plan-wide limits ('for plan limits across every category use get_usage_limits'). It also notes the prerequisite of organization context and that mutations are intentionally out of scope.

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 readOnlyHint annotation already signals that this is a read-only operation. The description adds useful behavioral context by noting that includeUsages should be set before deleting a snippet and that project context is required, going slightly 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?

The description is three sentences and every sentence earns its place: it states what is returned, clarifies includeUsages behavior, and gives usage guidance with a pointer to the sibling tool. There is no fluff or irrelevant 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?

Since there is no output schema, the description usefully explains that the response includes full Markdown content and rowVersion. It also mentions the prerequisite ('Requires project context') and the alternative tool for browsing, making the operational context sufficiently complete for a simple get-by-id operation.

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

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

All parameters have schema descriptions, so the baseline is met. The tool description adds a little extra context for includeUsages ('also list the pages embedding it'), but the parameter descriptions already convey their meanings. No parameter is left unexplained, but the description does not substantially enrich the parameter semantics 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 tool retrieves one snippet with its full Markdown content and rowVersion. It explicitly names the resource ('snippet') and the specific operation ('Get'), leaving no ambiguity about the tool's 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 provides direct usage guidance: 'Use this when you already have the snippet id' and points to the alternative for browsing: 'to browse a version's snippets use list_doc_snippets.' It also explains when to set includeUsages, making the tool's intended use 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 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?

Annotations already establish readOnlyHint=true, so the read-only safety profile is covered. The description adds useful behavioral context: endpointIds fetches up to 25 endpoints with the same detail per endpoint in one call, and project context is required. This goes beyond what the annotations alone 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 with no wasted words: the first states the core purpose, the second covers the batch mode, and the third gives routing guidance. Information is front-loaded and every sentence earns its place.

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

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

Given the readOnlyHint annotation, full schema coverage, and no output schema, the description adequately covers the return content, the batch limit, the required context, and the alternative tool. 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 has 100% description coverage, so the baseline is 3. The description adds the relationship that endpointIds can be passed instead of endpointId and returns the same detail per endpoint, which is helpful but does not add substantial syntax or format detail beyond what the schema already documents.

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') with a clear resource ('endpoint') and enumerates the returned content: parameters, request body, responses, and security schemes. It also explicitly distinguishes itself from list_endpoints by noting this is for when the endpoint id is already known.

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 when to use the tool: when you already have the endpoint id. It names list_endpoints as the alternative for browsing a spec's endpoints or finding an id, and it adds the project context requirement, leaving no ambiguity about 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 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?

The description mentions 'Requires project context', a behavioral prerequisite, and outlines what information is returned. The readOnlyHint annotation is consistent with the description, which implies no state changes by directing changes to another 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?

The description is two concise sentences that pack essential information without redundancy. Every phrase contributes to understanding the tool's purpose, usage, and requirements.

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 what the tool does, why to use it, what information it returns, and a prerequisite. Despite having no output schema, the description sufficiently explains the expected output.

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 specId is fully described in the schema as 'Public ID (GUID) of the API specification'. The description adds no additional parameter context, but since schema coverage is 100%, a 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 clearly states the verb 'List' and the resource 'version each environment currently pins for this spec', including details about frozen status and origin. This leaves no ambiguity about the tool's 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?

Explicitly provides the use case 'to see what each environment resolves to' and directs to an alternative tool 'promote_version' for changing pins. This is clear guidance on when and 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?

The readOnlyHint annotation already indicates no mutation, and the description adds meaningful behavioral detail by stating that secret values are always masked. It also mentions the organization context prerequisite. 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?

The description is brief and well-structured, with three concise sentences that cover purpose, behavior, usage direction, and context requirement. No unnecessary information is included.

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 a simple read operation: it explains what is returned (resolved variables), important behavior (masking), and usage context. Since there is no output schema, the description could ideally mention the exact return format, but the current level of detail is sufficient for most callers.

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 both parameters, including the optionality of projectId and the required environmentId. The description does not add additional semantic detail beyond the schema, so a baseline score 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 retrieves resolved variables for a specific environment and explicitly mentions that secret values are masked. The verb 'get' and resource 'environment variables' are specific, and the description helps distinguish it from related tools that export or resolve 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?

The description gives direct usage guidance: use this to read resolved values, and use set_environment_variables to change them. It also notes the requirement for organization context. However, it does not contrast with sibling tools like resolve_variables or export_variables, which could further clarify when this specific read tool is preferred.

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 exact information returned (last run time, result, spec version, pending count) and adds interpretive value ('Tells you which environment's results you can trust'). The readOnlyHint annotation already covers the safety profile, and the description adds behavioral context 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?

Two sentences with no filler. The first sentence front-loads the core function and output fields, the second provides usage guidance 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?

The description fully explains what the tool returns, when to use it, and a necessary precondition. With no output schema, the description covers the expected result fields. 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?

There are zero parameters, so the schema trivially covers 100% of them. The description doesn't need to explain any parameters; the baseline of 4 applies because the description appropriately omits parameter details that don't exist.

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: it provides per-environment verification of contract tests, listing last run time, result, spec version, and pending cases. It distinguishes itself from get_test_results by explicitly stating 'for one suite's run history use get_test_results'.

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

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

It explicitly instructs 'Use this for the per-environment overview; for one suite's run history use get_test_results', which clearly directs the agent to the correct tool for the intended scenario. It also notes the prerequisite 'Requires project context'.

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, it discloses that this tool can consume AI budget, may fall back to static text, and indicates the 'source' field communicates which mode was used. 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?

Every sentence adds value: purpose, output format, behavior, budget caveat, and sibling distinction. 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?

With no output schema, it sufficiently explains what the response will contain (markdown advice, source field indicating fallback vs AI). It also covers prerequisites and when to use an alternative.

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 single parameter findingId is fully described in the schema with origin guidance ('from get_security_findings'). The description adds no additional semantic detail beyond what the schema already 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?

States a specific verb ('Get'), resource (remediation advice for a finding), and output format (GitHub-flavored markdown). It clearly differentiates from list_security_guidance by focusing on a single finding.

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?

Explicitly says when to use for one finding and names the alternative list_security_guidance for the whole library. Also explains the AI budget condition that affects behavior.

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 communicates that this is a read-only operation, and the word 'Get' reinforces that. The description does not add extra behavioral details, but no contradiction exists and the annotation covers the main 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 concise, front-loads the primary purpose, and uses only two sentences to cover functionality, usage guidance, and prerequisites.

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 input and lack of output schema, the description provides sufficient context: what the tool returns, when to use it, and the alternative tool for browsing. 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?

The schema fully describes the only parameter, fixtureId, as the public GUID of the fixture to retrieve. Since schema coverage is 100%, the description does not need to add much, though it could mention format expectations beyond GUID.

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 fixture by public ID and returning both raw source and normalized JSON content. It also distinguishes itself from list_fixtures, which is for browsing.

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 says to use this tool when the fixture ID is already known and directs users to list_fixtures for browsing. It also notes that project context is required, giving clear usage conditions.

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 description states that for scope 'spec' it 'recalculates that spec's score on the spot — that writes a new snapshot and may raise alerts', which directly contradicts the readOnlyHint=true annotation. This is a serious inconsistency.

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 moderately concise, using two sentences plus an explanatory clause. It conveys all necessary guidance without unnecessary verbosity, though it could be slightly tighter.

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 tool's purpose, the two scopes, the side-effect for spec scope, and the alternative tool. It does not include an output schema, but the behavioral notes and usage guidance are 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 covers both parameters with defaults and descriptions (100% coverage). The description adds that specId is required for scope 'spec' and notes the project context requirement, providing extra semantic value beyond the schema.

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

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

The description clearly states 'Get the quality score' with a specific resource, though 'quality score' could be interpreted as different from 'governance score'. It distinguishes between org and spec scopes, providing sufficient clarity.

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?

Explicitly names the alternative tool 'get_governance_config' for thresholds and weights, and states the condition for using 'spec' scope requiring project context. This leaves no ambiguity about when 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 declare readOnlyHint=true, so the safety profile is already known. The description adds meaningful behavioral context: the includeUsage flag is only valid at spec level and is intended for pre-deletion checks, plus it clarifies the prerequisite 'Requires project context'. 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?

The description is three sentences, front-loaded with the core purpose, then the level/usage nuances, then the alternative tool and prerequisite. Every sentence earns its place with no redundant phrasing.

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 tool with 5 parameters, the description covers the return contents (schema details and rowVersion), the level semantics, the includeUsage behavior, the alternative for org level, and the project context requirement. No critical calling information 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?

Schema description coverage is 100%, so the baseline is 3. The description adds semantic value by clarifying that specId is required for level 'spec' and that includeUsage only applies at spec level, tying parameters to usage conditions that the schema alone doesn't fully convey.

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 'Get one header component with its schema details and rowVersion' – a specific verb and resource. It also distinguishes from the sibling get_org_header_component by explicitly scoping levels to 'spec' or 'project', so an agent can differentiate them 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?

The description gives explicit usage context: 'Use this for spec or project level; for the organization level use get_org_header_component.' It also advises when to set includeUsage ('do that before deleting one'), providing a clear when-to-use and an alternative tool. No ambiguity remains.

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 behavioral context: the org → project → spec cascade, grouping by status code, and that this tool does not return policy definitions. No contradictions 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 concise sentences, each earning its place: what the tool returns, the key alternative, and the definition-listing alternative. Slightly redundant with the schema by saying 'Takes an endpointId' when specId is also required, but overall tight and well-structured.

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

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

For a read-only two-parameter lookup with no output schema, the description covers response grouping, cascade behavior, alternatives, and a prerequisite. It does not detail the exact response format, but enough is provided 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 description coverage is 100%, so the baseline is 3. The description adds the 'whole endpoint' vs 'one response' nuance for endpointId, but it does not really elaborate on specId beyond the schema. It is adequate but not a major value-add.

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

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

The description clearly states a specific verb ('Get'), the resource ('headers that apply to a WHOLE endpoint'), the grouping ('by status code'), and the cascade context. It explicitly distinguishes this tool from get_resolved_headers, so an agent can select it correctly.

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 when-to-use guidance: use this for whole-endpoint headers, use get_resolved_headers for a single response, and use list_header_policies for policy definitions. It also notes the project context prerequisite, leaving little 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?

The readOnlyHint annotation already covers read-only behavior; the description adds context about returned data (scopes, components, impact) without conflicting with 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, well-structured, and front-loads the primary action. Each sentence adds necessary information without redundancy.

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

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

Covers what is returned, level requirements, and the distinction from org-level. Does not mention errors or edge cases, but these are not essential given the tool's simplicity and available annotations.

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

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

All four parameters are effectively explained: policyId implied by 'Get one header policy', level and specId clarified by 'spec needs specId or project', and includeImpact detailed with its effect. Schema coverage is 100% and description adds meaningful nuances.

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 it retrieves a single header policy with its scopes, components, and rowVersion, distinguishing it from listing (get_header_policies) and org-level (get_org_header_policy).

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?

Explicitly explains when to use (spec or project level), the need for specId at spec level, and directs org-level usage to a sibling tool. Also notes the includeImpact option is spec-level only.

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?

Annotations already establish readOnlyHint=true, and the description adds value by naming the returned data (schema, itemSchema, example, rowVersion) and noting the project-context requirement. It does not discuss error behavior such as unknown component IDs, but this is a minor gap for a simple read 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?

Three short sentences deliver the operation, returned data, sibling distinction, and an important precondition without filler. The core action is front-loaded and 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 two-parameter read tool, the description covers what is returned and when to use it, which compensates for the missing output schema. The 'Requires project context' note is useful, though it could be slightly clearer about how the context is provided.

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 provides full descriptions for specId and componentId at 100% coverage. The description reinforces the component-id usage pattern but adds no additional parameter-level detail beyond the schema, so the schema-coverage baseline 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 names the specific operation and resource ('Get one reusable media type component (OpenAPI 3.2)') and lists the key returned fields. It also distinguishes this fetch-by-ID tool from its browse sibling, list_media_type_components.

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 tells the agent to use this tool when the component id is already known and to use list_media_type_components for browsing. It also states the 'Requires project context' precondition, giving clear selection 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?

Annotations already declare readOnlyHint=true, so the description doesn't need to repeat that. It adds valuable context: the isDefault flag semantics and the project context requirement. It does not mention error cases or response format, but for a simple read-only getter with annotations, this is sufficient and adds meaningful behavior beyond the structured data.

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

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

Three sentences with zero waste. The core purpose is front-loaded, followed by the isDefault clarification and then routing/prerequisite guidance. Every sentence earns its place and the structure is clean.

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 getter with read-only annotation, the description covers what it does, what the response means (reviewers/guards, isDefault), and how to change it. It is complete for an agent to call correctly without additional context.

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%, with specId fully described as 'Public ID (GUID) of the API specification'. The description does not add any additional semantics for the parameter 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?

Description clearly states the verb 'Get' and the resource 'merge policy of a spec', and elaborates on what it contains (reviewer count and guards). It also explains the isDefault flag, which distinguishes the meaning of the response. This is specific and differentiates from sibling policy getters like get_alert_policy or get_deprecation_policy.

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?

Explicitly names the alternative tool (update_merge_policy) and the condition for using it ('to change it'). Also notes 'Requires project context', which hints at a prerequisite. This is clear routing guidance with no ambiguity.

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 read-only nature, and the description adds value by detailing the returned content (reviewers, decisions, comment thread) and the effect of includeAuditTrail. It does not contradict the annotation, and while it doesn't describe side effects, none are expected.

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

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

The description is concise, with each sentence serving a distinct purpose: defining the resource, providing a cross-reference, explaining a parameter, and giving usage guidance. It is well-structured and no unnecessary words are used.

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

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

Given the tool's simplicity and lack of output schema, the description adequately covers the core functionality, parameters, and relationship to other tools. It also notes the requirement of project context. Minor gaps like error conditions are not addressed, but for this level of complexity the completeness is strong.

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 covers all three parameters with descriptions. The description adds a useful cross-reference that the userId values under reviewers are what manage_merge_request('create') expects, and clarifies the purpose of includeAuditTrail. It enriches but does not replace 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 it retrieves a single merge request with its reviewers, decisions, and comment thread. The verb 'Get' and resource are explicit. It also distinguishes from related tools like list_merge_requests and get_branch.

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 when to use this tool: 'Use this when you already have the merge request id'. It also points to alternatives: 'to browse them use list_merge_requests' and 'for what the merge would actually change, use get_branch'. This gives clear 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 indicates a safe read operation, and the description appropriately describes the informational nature without adding conflicting details.

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, presenting the tool's purpose and view options in two clear sentences.

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 adequately conveys the tool's behavior and return nature for both views, though it lacks explicit examples or output details, which is acceptable for a simple getter.

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% with descriptions for both parameters; the description adds no new parameter information beyond what is already 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 inspects one mock rule and explains the two views ('drift' and 'state'), distinguishing it from sibling tools like list_mock_rules.

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 instructs to use this tool for inspecting one rule's drift or state and directs browsing to list_mock_rules, providing clear when-to-use 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 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?

The readOnlyHint annotation already covers the read-only nature, and the description reinforces it with 'Read.' It adds extra context about the required organization context and describes what each view returns, which 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 a few sentences but each adds value: purpose, view-specific outputs, when to use, and alternative. It is slightly verbose but well-structured and not repetitive.

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 there is no output schema, the description adequately explains what each view returns and mentions the prerequisite of organization context. It also points to the alternative tool for individual requests, covering key operational context.

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% with both params described, so baseline is 3. The description adds semantic depth by explaining what 'current' returns (running month with limit and reset date), 'history' (monthly totals), and 'breakdown' (current month split by project), 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 clearly states the verb 'Read' and the specific resource 'organization's mock request usage against its plan limit,' which is precise. It distinguishes itself from the sibling get_request_logs by expressly directing individual request lookups there.

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?

Explicit guidance is given: 'This is what to check when mock requests start being rejected' and 'Use this for request usage against the plan limit; for the individual requests use get_request_logs.' This leaves no ambiguity about when to choose this tool over 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?

The readOnlyHint annotation already communicates the read-only nature, and the description adds transparency about what the include flags do and what data is returned. No conflicting side effects are mentioned, and the description accurately reflects the tool's 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 concise yet informative, using a clear structure: a one-line purpose, a summary of the include flags, and explicit usage and context notes. Every sentence adds value without redundancy.

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

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

The description covers what the tool returns (recent checks, uptime/latency, alert policy, maintenance windows, fire/resolve history) and prerequisite context. Since there is no output schema, this textual description sufficiently informs the agent about expected results and usage constraints.

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?

Each of the six parameters has a clear, descriptive schema entry. The main parameter monitorId is explained as a GUID obtainable from list_monitors, and the include flags are each described with their effect. The description adds extra context on top of the schema, fully clarifying parameter 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 clearly states the tool fetches a single monitor with its recent checks, and differentiates it from list_monitors. It explicitly names the purpose and scope, making it easy for an agent to select this tool over 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 direct usage guidance: 'Use this when you already have the monitor id; to browse a project's monitors use list_monitors.' It also notes the prerequisite of project context, giving clear conditions for when to invoke 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?

The readOnlyHint annotation already declares the read-only nature, and the description aligns with that by using 'Get' and 'read the defaults'. No side effects are mentioned, but the annotation covers the primary behavioral trait.

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

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

Two concise sentences: the first lists the contained settings, the second states usage and alternative. No redundancy, clear structure, and all information is relevant.

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?

Although no output schema is provided, the description enumerates what the returned settings include, which gives sufficient context for an agent to understand the expected result. The mention of the update alternative provides additional operational context.

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 describes projectId with its default and type, achieving 100% coverage. The description repeats the 'requires project context' hint but adds little beyond the schema, so it neither enhances nor detracts from 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?

Clearly states the verb 'Get' and the resource 'project's monitoring defaults', enumerating the specific settings included. Explicitly contrasts with the sibling update_monitoring_settings, making the tool's purpose unambiguous.

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

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

Provides explicit guidance: 'Use this to read the defaults; to change them use update_monitoring_settings.' This directly tells the agent when to use this tool versus the alternative. Also notes the prerequisite of project context.

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?

The readOnlyHint annotation is present, and the description consistently indicates read-only behavior. It adds a necessary precondition ('Requires organization context') and explains the meaning of isUserOverride in the output, 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?

Two sentences, no redundant phrasing, and the content is well-organized: first the function, then scope behavior, then usage guidance. Every word adds value.

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

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

Explains the key output concept (isUserOverride) and the precondition for use. Since there is no output schema, the description sufficiently covers what the agent needs to know 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 coverage for the single parameter 'scope' is 100% (description and default are provided). The tool description does not add any information about 'scope' beyond what the schema already states, so 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?

Clearly states it reads notification preferences per category, and distinguishes itself from update_notification_preferences. The verb 'Read' and resource 'notification preferences' are specific and unambiguous.

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

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

Explicitly says when to use (to read preferences) and when not (to change, use update_notification_preferences). Also explains the difference between 'user' and 'org' scopes, giving clear guidance on 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?

The readOnlyHint annotation already indicates a safe read operation. The description adds useful behavioral context by stating the return includes 'full content and rowVersion', giving an expectation of what the tool provides. No contradictions.

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

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

The description is two short sentences, front-loaded with the action, and contains no fluff. It efficiently conveys purpose, usage, and key return 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 single-parameter read-only tool with no output schema, the description is complete: it states what it returns, when to use it, and the sibling alternative. 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?

The only parameter, templateId, is fully described in the schema as 'The public Id (Guid) of the template', and the description also references the template ID, providing complete 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?

States exactly what it does: retrieve one organization documentation template with full content and rowVersion. It clearly distinguishes from siblings by indicating it is used when the template ID is already known, and it mentions list_org_doc_templates as the alternative for browsing.

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?

Explicitly tells when to use this tool ('when you already have the template id') and when to use the sibling ('to browse them or find an id use list_org_doc_templates'). This gives clear, actionable 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 signals no side effects, so the description doesn't need to repeat that. It adds useful context about the includeUsage parameter's purpose (checking endpoints before deletion), which aids in understanding the tool's behavior. No contradictions 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 compact and to the point, with no redundant wording. It conveys all essential information in two sentences and a short clause, 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 description indicates what is returned (schema details and rowVersion) but does not enumerate all response fields or error scenarios. Given the tool's simplicity and the presence of sibling tools for listing, this is sufficient for an agent to know when and how to invoke it correctly.

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

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

The schema already covers all three parameters with descriptions, achieving 100% coverage. The description adds marginal value by explaining the purpose of includeUsage (listing referencing endpoints) and implies that specId and componentId are identifiers needed for lookup. No additional semantics beyond schema are necessary.

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 'Get' and the specific resource 'reusable parameter component', including what is returned (schema details and rowVersion). It distinguishes this tool from list_parameter_components and other component getters by focusing on a single component by ID.

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?

Explicitly states when to use this tool ('when you already have the component id') and when to use the alternative ('to browse them or find an id use list_parameter_components'). It also mentions a precondition ('Requires project context') and provides a practical hint about includeUsage before deletion.

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?

The readOnlyHint annotation already signals no side effects, and the description adds useful behavioral context about requiring organization context and falling back to the active project.

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, with no redundant or unnecessary 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?

Despite lacking an output schema, the description clearly conveys what the tool returns and the conditions under which it operates, making it complete for this simple tool.

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

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

The schema already documents the parameter fully, and the description adds meaningful clarification by explaining the GUID format and the behavior when projectId is omitted.

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 action ('Get detailed information about a project') and explicitly distinguishes itself from list_projects, making its purpose 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?

Provides explicit guidance on when to use the tool (when project id is already known), when to use the alternative (list_projects), and notes the prerequisite to call set_context first.

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 safety profile, and the description adds meaningful behavioral context: it lists already-published events only and requires project context. It does not describe return ordering or pagination, but that is a minor gap for a read-only listing 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?

The description is two sentences with no filler. The primary action is front-loaded, and the alternative tool plus prerequisite are stated in a compact, useful 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 listing tool with a fully documented schema and a readOnlyHint, the description plus schema gives an agent everything needed to call it correctly: the subject, the distinction from scheduled publishes, and the context requirement. No output schema is present, but the description communicates what the result contains.

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 100% parameter coverage, so the schema already documents all four parameters including defaults and limits. The description adds no new parameter-level meaning, but it doesn't need to; 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 uses a specific verb ('List') and names the resource and attributes returned: when a version was published, to which target, and by whom. It also distinguishes itself from get_scheduled_publishes, so an agent can 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?

The description explicitly states when to use this tool ('for what has already been published') and names the alternative for future publishes ('get_scheduled_publishes'). It also notes the prerequisite of project context.

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 context about requiring project context and the purpose of rowVersion for future updates. No contradictions 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 concise, two sentences, and directly states the tool's function and usage context without extraneous detail. It is well-structured and front-loaded with the primary purpose.

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 fully explains what the tool does and when to use it. The absence of an output schema is not an issue because the description does not need to specify return values; the tool name and details are 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?

The schema provides 100% coverage of all three parameters with clear descriptions. The tool description does not add additional meaning beyond what the schema already states, so baseline score 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 states the tool retrieves a request body component, including its schema definition and rowVersion, and optionally usage details. It explicitly distinguishes itself from list_request_body_components, making its purpose unambiguous.

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

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

It provides explicit when-to-use guidance: use when you already have the component id, and use list_request_body_components to browse or find an id. It also notes 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?

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 indicates a non-destructive operation, and the description adds useful behavioral details such as requiring project context and the effect of setting includeUsage. No contradictions or hidden side effects are mentioned.

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 three focused sentences with no redundant or irrelevant information. It front-loads the core purpose and then provides necessary usage context.

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-like tool with no output schema, the description sufficiently explains what will be returned (schema, headers, rowVersion) and the optional includeUsage behavior. It also communicates the project context prerequisite, making it complete enough for an agent to call correctly.

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

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

The schema already covers all three parameters with meaningful descriptions. The tool description adds some usage nuance, such as having the component ID beforehand, but does not significantly expand 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 clearly states the tool retrieves a single reusable response component with its schema, headers, and rowVersion. It also distinguishes itself from list_response_components by specifying that it is for when a component ID is already known.

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