Gostman

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

Annotations already declare this a safe, idempotent read, so the description doesn't need to cover safety. It adds genuinely useful behavioral detail the schema cannot: credentials are masked, variables are rendered as {{name}}, and options lists only non-default settings — all of which shape how the agent should interpret the output.

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-loaded with the resource and the full field list, then the masking/variable rendering caveat. Dense but every clause carries information; minor cost is the long enumerated list read as a run-on.

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

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

With an output schema present and rich annotations, the description needn't explain return shape or safety, and it covers the one thing schema can't — masking and variable substitution. The only real gap is routing guidance against list_requests/send_request for the same request.

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 is one parameter with 100% schema description coverage, and the schema already explains the id/name resolution and the folder-path disambiguation for duplicate names. The description adds no further parameter guidance, 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?

States a specific verb (show) and resource (one saved request) and enumerates the contents returned (URL, headers, body, auth, vars, assertions, extractions, scripts, example names), which clearly distinguishes it from summary-level siblings like list_requests and from response-oriented tools like last_response.

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

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

Usage is only implied: 'one saved request' contrasts with list_requests in the parameter schema, and 'saved' implies a stored definition rather than a live response. There is no explicit statement of when to prefer this over list_requests or send_request, and no exclusions or prerequisites.

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 annotations, the description discloses concrete behavior: collection settings are adopted only when the workspace has none, scripts and OAuth 2.0 settings are stripped and reported in leftOut, warnings describe the source, and imports containing credentials, local file reads, or local command execution are refused. These are precisely the behavioral traits an agent needs for a write-capable import 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 front-loaded with the core action and then layers on the key behavioral caveats. It is dense but each clause carries useful information; the only minor cost is a long paragraph rather than shorter separated statements.

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 an output schema for the return value, full schema description coverage, and annotations already declaring openWorld and non-idempotent behavior, the description supplies enough additional context about sanitization, refusal conditions, and non-destructive workspace behavior to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents url, folder, format, and content in detail. The description reinforces what documents can be imported but adds no parameter-specific syntax or constraints beyond the schema, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: it adds requests to the workspace from named source formats. It does not explicitly differentiate itself from siblings such as save_request or lint_spec, but the import/collection scope is unambiguous from the enumerated formats.

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

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

Usage is implied by the list of supported import sources, but the description never says when to choose this tool over alternatives like save_request or lint_spec. The note that existing content is not changed provides useful context but is not an explicit usage rule.

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, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds genuinely new behavior: the response is session-scoped and cached, and the tool silently performs a comparison against a saved example, reporting status, content type and differing JSON paths. That silent side-effect of comparison output is the kind of context annotations cannot carry.

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, zero waste. The primary behavior (show cached response without resending) comes first, and the conditional comparison behavior is correctly subordinated behind 'When the request has saved examples'.

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

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

With an output schema present, the description needn't enumerate return values, and it wisely stays out of that. It covers the key non-obvious facts an agent needs: session-scoped availability, no re-send, and implicit example comparison. A note on the failure mode when no prior response exists would close the remaining gap.

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%, including select, example, shape_only and max_body_bytes, so the schema already carries the parameter burden and a baseline 3 applies. The description ties 'saved examples' to the example parameter and hints at what comparison yields, but adds no format, defaulting, or interaction detail 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?

States a specific verb and resource — 'show the last response a saved request got in this session' — and immediately scopes the source ('from send_request or run_folder'), which distinguishes it from every sibling that would produce a fresh response. An agent can tell without opening any schema that this is a cached-read tool, not a request-firing 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?

'Without sending it again' gives a clear condition for choosing this over send_request and run_folder, which are the obvious alternatives. It does not, however, address when to prefer this over get_request or list_requests, nor what happens when no prior response exists in the session.

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real value beyond that by specifying the rule categories (missing operation ids, undeclared path params, broken $refs) and stating that it returns counts and findings.

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 tight sentences: the first front-loads the action and scope with a compact rule enumeration, the second states the return shape. 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?

An output schema exists so return details are covered elsewhere, and the annotations carry the safety profile. The description supplies the rule set and supported formats, leaving only cross-tool routing guidance as a minor gap.

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 the url and content parameters are fully documented in the schema, including the host-restriction caveat. The description adds nothing about parameter usage, which is acceptable at full coverage but earns only the baseline.

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

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

Names a specific verb (check/lint) and resource (OpenAPI 3 or Swagger 2 document) and enumerates the concrete rule families applied. No sibling tool does validation, so an agent can route here unambiguously.

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

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

Usage is implied by the resource described (a spec document) but the description never states when to prefer this over, say, import_requests, nor when linting is unnecessary. No explicit triggers or exclusions are given, leaving context to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: values are never returned, variables must be referenced as {{name}}, and secrets resolve from the developer. Only the absence of any note on environment ordering/scoping keeps it from a 5.

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?

Front-loaded with the core listing behavior, followed by the value-redaction rule and the secret-resolution guidance, each of which earns its place. The final clause on --var-from-env is slightly dense but remains useful.

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?

An output schema exists, so return-value details need not be restated, and the description covers the two things an agent must know: values are redacted and how to reference variables. Complete for a zero-param listing tool, though it leaves environment scope relative to siblings implicit.

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

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

The tool takes zero parameters, so the schema carries no semantics to supplement. Baseline 4 applies; nothing in the description misleads about inputs.

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 ('List the environments') and precisely describes the returned content: variable names, the active environment, and session-valued variables. An agent can distinguish this read-only discovery tool from set_environment/set_variables without opening the sibling 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 actionable context for its use: it notes that secret values come from the developer and instructs the agent to ask the developer to pass missing ones with --var-from-env. It stops short of explicitly naming alternatives like set_environment, so a 4 rather than 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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is fully covered structurally. The description adds that results include hasTests and saved-example flags, but says nothing about result volume, ordering, or pagination for a workspace-wide list.

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, front-loaded with the action and the returned fields before the usage tip. The field enumeration is slightly long given an output schema exists, but it is compact and informative.

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?

A read-only listing tool with an output schema; the description correctly avoids re-explaining return values and covers purpose plus entry-point guidance. The only gap is noting that results may be large and how to narrow them via the folder filter.

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 folder parameter is fully documented in the schema (names and nested paths, plus the omit-to-list-everything default). The description never mentions the folder filter, but the baseline of 3 applies when the schema does the heavy lifting.

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?

Specific verb ('List') plus resource ('API requests saved in this Gostman workspace'), with an enumeration of returned fields (id, method, URL template, hasTests, examples) that lets an agent predict the response shape.

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?

'Call this first to find a request to send instead of writing a curl command' gives a clear entry-point rule and steers away from an ad-hoc alternative. It does not name sibling tools like get_request or send_request, so the routing is implied rather than exhaustive.

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 flag destructiveHint=true and openWorldHint=true, and the description adds genuinely useful context beyond that: request volume/rate ceilings, a 30-second wall clock, and that targets must be hosts 'this session may call'. The ownership warning is real safety context, though it does not say what side effects repeated real requests may cause on the target.

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, front-loaded with the action and outputs, then constraints and safety. Tight overall; the constraints clause largely duplicates schema maximums, which is the one mild 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?

An output schema exists so return shape need not be spelled out, and the description still previews the reported metrics. Combined with the safety and scope statements, an agent has enough to invoke it correctly; only the interaction between the rps/requests/duration caps is left to inference.

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 per-parameter descriptions, so the schema carries the semantics. The description only restates the limits in prose ('Limited to 20 at once, 30 seconds and 5000 requests') without adding syntax or default-interaction 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?

States a specific verb and resource ('Send one saved request many times at once') plus the reported outputs (throughput, latency percentiles, status codes, error samples). It implicitly contrasts with the single-send sibling send_request by emphasizing 'many times at once', but never names an alternative, so it stops short of full sibling differentiation.

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

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

'Only test systems the developer owns' gives a prerequisite/eligibility rule, and the caps define operational bounds. However there is no explicit when-to-use guidance versus send_request or run_folder, and no statement of what to do when a test needs to exceed the 20/30s/5000 limits.

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, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is fully covered and the description does not need to restate it. The description adds real behavioral value by revealing this is an aggregate snapshot (liveness + address + route list + recent traffic) rather than a single-value read, but it does not say what happens when the server is not running (error vs. a status field).

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

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

A single sentence, front-loaded with the core verb and resource, that enumerates only the four things the caller actually gets back. No preamble, no filler, nothing 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?

With an output schema present, the description is not obliged to explain return values, and annotations cover the safety profile; the remaining job is helping the agent decide when to call, which it mostly does. The one gap is the not-running/failure case, which matters for a liveness check and is left unstated.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the schema is trivially complete. The baseline of 4 applies; nothing in the description misleads about inputs.

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 definition pairs a specific verb ('Report') with a specific resource (the mock server) and then lists exactly what the report contains: running state, address, workspace-refreshed routes, and recent requests. That is far more informative than the title alone and clearly marks it as a read-only status snapshot rather than a request listing ('list_requests') or teardown ('stop_mock'). It falls short of 5 because it never names the sibling tools it should be preferred over.

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

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

The description makes the usage clear by implication: it is the diagnostic/preflight call an agent makes to confirm the mock server is up and to see what routes it is serving. However, it states no explicit when-to-use or when-not-to-use condition and points to no alternative when, for example, the agent only wants responses ('last_response') or traffic ('list_requests').

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 disclose destructiveHint=true, openWorldHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds beyond that by explaining ordered execution of every request, scripts and assertions, tag-based subsetting, iteration behavior, and failed-request return details. It does not add auth, rate-limit, or side-effect specifics, but the annotations carry the main risk signal.

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

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

The description is front-loaded with the core action and scope, then adds parameter behavior, a use case, and return details in three efficient sentences. Each sentence contributes useful information, and there is no boilerplate 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?

Given six optional parameters, full schema description coverage, rich annotations, and an output schema, the description is complete enough to call the tool correctly. It covers folder versus workspace scope, tag filtering, data/iteration repetition, intended use, and return shape without over-explaining schema-covered details.

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

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

Schema description coverage is 100%, so the baseline is already a 3. The description adds useful semantics beyond the schema by explaining that tags and exclude_tags narrow the run to subsets such as smoke tests and that data and iterations repeat the run. It omits bail, but the schema fully documents that 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: sending every request in a folder or the whole workspace in order, with scripts and assertions. It clearly distinguishes this batch collection-runner behavior from single-request siblings through the folder/workspace scope and execution order. The 'check that an API still works after a change' framing also separates it from load-focused 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 gives a clear usage context: checking that an API still works after a change, and narrowing runs to smoke tests with tags. It does not explicitly state when not to use this tool or name alternatives like send_request for a single request. This matches a clear-context-but-no-exclusions rating.

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 destructiveHint=true and idempotentHint=false, so the bar is lower; the description still adds real context by disclosing partial-update semantics, the secret-refusal policy requiring {{name}} references, and the identity fields returned. It does not warn that array/map fields (tags, headers, assertions, extractors) are replaced wholesale, which is the most likely source of surprise given destructiveHint=true.

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

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

Four sentences, front-loaded with create/update, then the partial-update rule, then the secret constraint, then the return shape. No restatement of the title, no filler, and the most consequential constraint (secrets refused) is placed before the return 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?

The schema is rich (12 parameters, nested objects, enums) and an output schema exists, so return-format explanation is redundant but harmless. Given destructiveHint=true, the description should have flagged that repeated fields are fully replaced rather than merged — the one behavioral gap an agent could trip on. Otherwise create/update/partial/secret semantics are all 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?

Schema coverage is 100%, so the baseline is 3; the description earns a bump by adding a cross-cutting constraint that the schema states only piecemeal — any value matching a credential or variable must be written as {{name}}. That rule applies across url, headers, and body and is the single most important parameter-level fact for calling this correctly.

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

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

The description opens with a concrete verb and resource ('Create a request in the workspace, or update one by id') and explains the outcome — the developer finds it in the Gostman app and can re-run it. It clearly separates create vs. update behavior, which distinguishes it from read-only siblings like get_request and list_requests, though it never names an alternative explicitly.

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

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

It states the two modes of use (omit id to create, supply id to update) and adds the partial-update rule ('Only the fields you give are changed'). What's missing is routing against siblings such as send_request, import_requests, or run_folder, so the agent must infer when saving is preferred over sending or importing.

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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description does add genuinely useful behavior beyond them: findings are masked to at most the first four characters, and each hit explains where and why. It says nothing about scan cost, latency, or limits on the number of findings, which for a whole-workspace scan would matter.

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, front-loaded with the verb and scope, then the output shape, then the trigger. No repetition of the title and no filler.

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

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

An output schema exists so return values need not be explained, and the description still gives the one detail an agent needs to interpret results safely (masked values, where/why per finding). Adequate for a zero-required-parameter read-only scan; only missing scan scale/cost 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 description coverage is 100% and there is only one optional boolean, so the schema carries the parameter meaning unaided; baseline 3 applies. The mention that saved examples are among the scanned surfaces implicitly signals why skip_examples exists, but the description never refers to the parameter directly.

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 (look for) plus the exact resource class (credentials) and enumerates the four surfaces scanned: requests, environments, scripts and saved examples. That scope is distinct from any sibling like lint_spec or list_requests, so the agent can choose it 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?

"Run it before the developer commits or shares the workspace" gives a concrete trigger condition, which most definitions lack. It stops short of naming exclusions or alternatives (e.g. when not to bother, or what to pair it with), so it is clear context rather than a full selection rule.

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?

Goes well beyond the annotations (openWorld, destructive, non-idempotent) by explaining that secrets never appear in the command or result, that logins persist across calls, and that saved requests run scripts, extraction rules and assertions. It also details the returned JSON summary fields, truncation semantics, and the meaning of failed/unresolved/withheld.

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?

Front-loaded with purpose and the curl alternative before the return-value details. It is dense but nearly every sentence carries actionable information; the long list of summary fields is the main reason it isn't 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?

Given 10 parameters and a destructive/openWorld profile, it covers side-effect-relevant behavior (persisted auth, withheld secrets, failed/unresolved/withheld signals) and even explains output despite an output schema existing. It doesn't explicitly warn that sent requests can mutate remote server state, which would fully round out a destructive 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 coverage is 100%, so the schema already documents each parameter, but the description adds cross-parameter guidance: use select or raise max_body_bytes only when body.truncated is true. That connection between truncation and the narrowing parameters is meaning the schema alone doesn't give.

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 ("Send a saved request ... or an ad hoc one") and immediately disambiguates the two modes by naming which parameter selects each. It also distinguishes itself from the obvious external alternative, curl, so an agent knows exactly what this tool is for.

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 to prefer this over curl because variables/auth/cookies/OAuth are filled in and the login persists across calls, and gives the saved-vs-ad-hoc selection rule. It stops short of naming sibling alternatives like run_folder or last_response, so the boundary against those tools is not stated.

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

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

Despite annotations only declaring safety flags, the description discloses the actual side effects: variables are re-read, variables set by earlier requests are cleared, and cookies/OAuth tokens are preserved. That is exactly the kind of non-obvious state consequence an agent needs before switching environments mid-session.

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 tight sentences: the effect is front-loaded, then the state-preservation detail follows with no filler. Every clause carries information an agent cannot get from the 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?

Output schema exists, so return values need no explanation, and the description covers the mutation's effect on session state well. It stops short of noting behavior for an invalid or unknown environment name, which is the one remaining gap for a state-mutating 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 coverage is 100% for the single 'name' parameter, including the note that it matches list_environments output, so the schema does the heavy lifting. The example values 'Local' and 'Staging' add a little color but no syntax or format detail 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 and resource ('Choose the environment') and explains the effect: its variables fill in {{name}} for the rest of the session. That is enough to separate it from list_environments, but it never contrasts with set_variables, which is the nearest ambiguous sibling.

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

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

The 'for example to switch from Local to Staging' clause implies the usage context, but there is no explicit when-to-use / when-not guidance and no named alternative. The routing hint ('as list_environments shows it') lives in the schema, not the description, so discoverability of valid values is only implied.

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 cover readOnly=false, destructive=true, idempotent=true, openWorld=false, and the description adds real value beyond them: credentials and developer-marked secrets are rejected, and setting values never expands the hosts requests can reach (a security-relevant constraint not expressible in annotations). It omits the behavior most tied to destructiveHint — whether existing variable values are overwritten or the set is replaced — which is a notable gap for a destructive 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 compact sentences, front-loaded with what is saved and followed by the refusals. Minor cost: 'Values set here never let requests reach a new host' is terse and takes a moment to parse, but each sentence carries information.

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

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

With an output schema present and rich annotations, the description needn't explain returns, and it covers purpose, constraints, and credential alternatives. The remaining hole is overwrite/merge semantics and whether unlisted variables are preserved — relevant given destructiveHint=true and the nested variables map.

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 (variables map and environment) are already documented, including the example and the create-if-missing behavior. The description only echoes that these must be plain values, adding minimal semantics beyond the schema; 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?

States a specific verb+resource ('Save plain variable values ... in an environment file of the workspace') and scopes it with concrete examples (baseUrl, userId) and hard limits (credentials and secrets refused). It distinguishes itself implicitly from set_environment by emphasizing value-setting in a file plus the note that new hosts never become reachable, though it never names the sibling that switches the active environment.

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 clear context: use this for plain values that later requests and the developer's app should consume, and it routes credential cases elsewhere ('the developer sets those in the app or with --var-from-env'). It also points at list_environments for naming the target environment. It stops short of explicit when-not-to-use guidance relative to siblings like set_environment.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds useful output context (address plus per-request served status and failure reason), but omits the key lifecycle fact that the server keeps running until stop_mock and gives no hint about non-idempotent behavior or port-in-use failures, which is what an agent most needs to know before starting a long-lived process.

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 it does, when to use it, and what comes back. Purpose is front-loaded and the use case follows immediately with no filler.

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

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

With an output schema present, the description needn't explain the return shape, and it correctly summarizes it in one clause. What remains missing is lifecycle context — that the server persists until stop_mock and what happens on a port conflict — but nothing an agent needs to formulate the call itself is 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% with bounds and a documented default port of 4010, so the schema carries the parameter documentation. The description contributes nothing about port choice or delay_ms semantics, making this the baseline case where structure does the work.

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?

Names a specific verb and resource (Start a mock server) and explains the mechanism precisely: it answers each saved request's path with its saved example response. This clearly separates it from stop_mock, mock_status, and send_request without needing to open any 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?

Explicitly states the use case: develop against an API that is not running, which tells the agent when to reach for it. It stops short of naming stop_mock as the follow-up or saying when to prefer mock_status instead, so the alternatives are only implied.

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 idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety profile is largely covered. The description adds one useful behavioral constraint - it only stops a server that start_mock launched - but says nothing about failure behavior or whether in-flight requests are dropped.

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

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

A single short sentence with the action front-loaded and the scope qualifier attached. Every word earns its place and there is no filler.

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

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

With no parameters, rich annotations, and an output schema that carries return values, the description only needs to establish purpose and scope, which it does. A note on the no-server-running case would close the remaining gap, though idempotentHint partially covers it.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The schema's empty properties object matches the parameterless contract implied by the 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 (stop) and resource (the mock server), and scopes it to the server created by start_mock, which cleanly separates it from that sibling. It is clear but deliberately terse, with no indication of what state or side effects the stop 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?

Usage is implied through the reference to start_mock: call this after starting a mock. There is no explicit when-not guidance, no mention of what happens when no mock is running or whether other operations must be done first.

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