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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so the write nature is covered. The description adds one genuinely non-obvious side effect: without a workspace, the collection lands in the oldest personal Internal workspace owned by the caller. That said, this note conflicts with the schema, which marks workspace as required, leaving the agent unsure which source to trust, and nothing is said about permissions, duplicate-name handling, or limits.

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

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

Two short sentences with the core action front-loaded and the caveat clearly separated under a bolded 'Note:' label. No filler, no repetition of what the schema already states.

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

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

The tool is complex (deeply nested collection object, no output schema), yet the description says nothing about the return value, error modes, or what happens on name collisions. It is minimally viable because the schema is fully documented and annotations cover the safety profile, but the lack of any response or failure information leaves a real gap for a create 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?

Schema description coverage is 100%, so the schema already documents both parameters and their nested structure, giving a baseline of 3. The description adds a pointer to the external Collection v2.1.0 schema doc, which is useful when constructing the large nested 'collection' object, but it gives no additional semantics for the workspace parameter and its stated default contradicts the schema's required flag.

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 gives a specific verb and resource ('Creates a collection') and pins the accepted format to the Postman Collection v2.1.0 schema, which is a meaningful detail. It does not, however, distinguish this tool from close siblings such as createCollectionRequest, generateCollection, or duplicateCollection, so an agent must infer the boundary 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?

There is no when-to-use guidance, no prerequisites, and no naming of an alternative for the create-a-collection case. The only contextual sentence describes a default placement behavior, which is a behavioral detail rather than usage guidance for choosing this tool over its siblings.

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 this is not read-only, not idempotent, non-destructive, and open-world. The description adds a useful behavioral consequence: omitting `name` creates a blank-name request, but it does not cover permissions, error behavior, or return values.

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

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

The description is short and front-loads the core action, then adds a docs pointer and name caveat. The name caveat duplicates the schema's `name` description, which is minor redundancy but not excessive.

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 15-parameter mutation tool with no output schema, the description covers the core action and the main naming gotcha, while the schema and annotations carry most remaining detail. It still omits return behavior, collection/folder prerequisites, and sibling alternatives.

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 15 parameters in detail. The description only repeats the `name` recommendation and defers the rest to external documentation, adding little beyond the structured 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: "Creates a request in a collection." It is clear what the tool does, but it does not explicitly differentiate it from siblings such as createCollectionResponse or updateCollectionRequest.

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 no explicit when-to-use guidance, no when-not-to-use guidance, and no alternatives among sibling tools. The only additional usage note is about passing `name`, not about selecting this tool.

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

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

Annotations already declare this is a mutating (readOnlyHint=false), non-idempotent, non-destructive, open-world operation, so the safety profile is covered. The description adds one genuine behavioral consequence — omitting name yields a blank-named response — but says nothing about permissions, whether re-calling duplicates the response, or what happens to the parent request.

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?

Purpose is front-loaded, followed by a doc pointer and a short note; three compact chunks with no filler. The external-documentation redirect is slightly evasive but it keeps the definition tight.

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 19-parameter tool with nested objects and no output schema, the description delegates the bulk of body semantics to an external Postman schema link. Schema coverage compensates for the parameter side, but the description never indicates what the call returns (created object, ID, status), which an agent calling a create endpoint would want.

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 all 19 properties documented including enums and nested header objects, so the baseline is 3. The description's name-property note merely repeats the identical text already present on the name field and adds 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 clear verb and resource: 'Creates a request response in a collection.' An agent understands it persists a saved response example. However, it never distinguishes itself from the very similarly named sibling createCollectionRequest, and the phrase 'request response' is ambiguous enough that an agent could confuse the two.

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

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

No guidance on when to create a response versus creating a request (createCollectionRequest) or a collection (createCollection), and no stated prerequisites such as whether the parent request must already exist. The only actionable advice concerns the name property, which is parameter-level, not usage-level.

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 valuable behavioral context beyond annotations: request body size limit (30MB), handling of 411 error, default workspace selection, and the limitation on modifying only shared variable values. These details help the agent understand side effects and constraints without contradicting the readOnlyHint=false 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 main description is concise, and the note is structured with bullet points. However, the note about shared variables is lengthy and could be trimmed, though it is relevant. Overall, it is not excessively verbose.

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 operational details like size limits and error handling, but it does not mention the success return value or any prerequisites. The workspace parameter discrepancy (optional in description vs required in schema) leaves some ambiguity. Given the tool's complexity and lack of output schema, more detail on creation outcomes would be helpful.

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 baseline is 3. The description adds meaningful semantics for the workspace parameter (defaults to oldest personal Internal workspace when omitted) and for the values parameter (only shared variable values can be modified via API). However, there is a contradiction: the schema marks workspace as required, while the description implies it is optional, which could confuse the agent.

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 'Creates an environment.' which clearly states a specific verb and resource. It distinguishes from sibling tools like createCollection and createWorkspace by specifically targeting environments.

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 context about default workspace behavior and error handling, but does not explicitly state when to use this tool versus alternatives (e.g., updateEnvironment). There is no mention of exclusions or comparison with sibling create tools.

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

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

Annotations already mark this as non-readonly, non-idempotent, and non-destructive. The description adds a meaningful behavioral requirement: the collection property must be a UID (ownerId-collectionId), not a bare ID, and gives two ways to resolve it. It also clarifies workspace placement, going beyond the structured annotation 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?

The description is front-loaded with the core action, then uses short actionable bullets for UID resolution and workspace guidance. Every line earns its place: the UID requirement is essential, the resolution steps are compact, and the workspace preference is a one-line reinforcement.

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 schema fully documents the mock/name/private/environment fields and the description covers the non-obvious UID requirement and workspace handling, the agent has everything needed to construct a valid call. No output schema exists, so return values do not need explanation. The description closes the main correctness gap left by the 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?

Though schema coverage is 100%, the description materially enriches the `collection` parameter by warning that bare IDs are wrong and explaining how to derive the UID. It also upgrades `workspace` from a simple ID to a placement scoping hint with the instruction to prefer explicit workspace scoping. This adds high-value meaning beyond the JSON Schema descriptions.

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

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

The description opens with 'Creates a mock server in a collection,' a clear verb-resource statement that identifies the tool's core action. The title and description together differentiate createMock from the sibling updateMock, publishMock, getMock, and getMocks.

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 when-to-use guidance by requiring the collection UID and providing a resolution path (GET /collections/{id}, GET /me) and by recommending explicit workspace scoping. It does not explicitly say 'use updateMock when the server already exists,' so it misses formal alternative comparison, but it is far above merely implied 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?

The annotations already mark this as a write operation (readOnlyHint:false), and the description adds valuable behavioral details: file size limit (12 MB), folder creation when paths contain '/', and the requirement that multi-file specs have exactly one ROOT file. These constraints go beyond the schema and help set expectations.

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 primary action, followed by a focused bullet list of five relevant notes. No redundant content; each note addresses a likely usage question (supported formats, folder behavior, file size).

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 create operation with a complex 'files' array, the description covers supported formats, folder creation, root file constraints, and file size limits. It doesn't describe the return value or error conditions, but given the annotations and schema, this is largely sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% for all four parameters. The description adds meaningful context about the 'files' parameter, specifically how path separators create folders and the ROOT/DEFAULT file type requirement for multi-file specs, which is not fully evident from 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 'Creates an API specification in Postman's Spec Hub', specifying the action and resource. It also distinguishes itself by mentioning single or multi-file specs, making it clear this creates a spec rather than merely adding files to an existing one (as with createSpecFile).

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 rich context about supported formats and constraints, but it doesn't explicitly state when to use this tool versus createSpecFile or other spec-related siblings. There's no explicit alternative or exclusion, so an agent must infer the boundary.

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 indicate a non-read-only, non-destructive, non-idempotent operation. The description adds valuable behavioral details beyond annotations: folder creation when '/' is in the path, DEFAULT file type assignment, single root file limit for multi-file specs, and a 10 MB file size cap. 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 concise: a single-sentence purpose followed by four focused bullet points. It front-loads the main action and uses formatting that makes the additional notes easy to scan. Every sentence contributes useful information (folder behavior, file type, root file rule, size limit).

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 create operation with no output schema and full annotation coverage, the description covers creation behavior, file type, size limits, and multi-file constraints. It does not explain response behavior or what happens if the file already exists, but the annotations (non-destructive) and sibling context mitigate that gap. Overall sufficient for an agent to invoke 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 covers all three parameters with descriptions (100% coverage), so the baseline is 3. The description adds specific semantic value for the 'path' parameter—explaining that a forward slash triggers folder creation—which goes beyond the schema's 'file's path' description. It does not add much for 'specId' or 'content', but the path insight is meaningful.

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 ('Creates') and resource ('a file for an OpenAPI or a protobuf 2 or 3 specification'), clearly distinguishing it from sibling tools like createSpec (which creates a spec) and updateSpecFile (which modifies). It also scopes the file types supported, making the purpose unambiguous.

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

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

The description implies when to use this tool: to create a file within a spec, with notes about folder creation and multi-file root constraints. It does not explicitly name alternatives, but the context of 'file for a specification' reasonably separates it from createSpec. The note on multi-file roots adds usage-relevant 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 non-readonly, non-destructive, open-world behavior, so the bar is lower; the description clears it by disclosing concrete failure behavior (403), rate-limit constraints on publishing, public workspace name uniqueness, and the conditional teamId requirement. These operational details add genuine context beyond the annotation hints, though no response-format or rollback info 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?

The description is front-loaded with the one-sentence purpose followed by five tightly-scoped bullets, each carrying operational weight—permissions, plan restrictions, rate limits, naming, and conditional requirements. Every sentence earns its place, though it's slightly long for the simplest read of the action.

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 create operation with no output schema, the description covers the key edge cases: permission failures, plan limits, uniqueness, and a conditional required field. It's thorough given the tool's simplicity, leaving no major operational gap, though it doesn't describe the returned workspace object.

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 the nested workspace object fully documented, so the baseline is 3. The description's teamId note is duplicative of the schema's own teamId property description, and it adds no new parameter semantics beyond what the schema captures.

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

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

The description opens with the specific verb-resource pairing 'Creates a new workspace,' which unambiguously states the operation and target. This clearly distinguishes it from siblings like getWorkspaces, getWorkspace, and updateWorkspace in the broader CRUD family.

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 rich operational context—403 Forbidden behavior when permissions are lacking, rate limits on public workspaces, and name-uniqueness constraints—which implies when the call will fail. However, it never explicitly tells the agent when to select this tool over alternatives (e.g., updateWorkspace for modifications), so usage guidance is implied rather than stated.

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

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

Annotations already indicate readOnlyHint=false, so the description's 'creates' is consistent. It adds valuable behavioral context by indicating the operation is asynchronous (via the status endpoint) and not destructive, going beyond the basic write-operation hint. It does not detail permissions or potential side effects, but the async nature is key 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?

The description is two concise sentences: the first states the core purpose, and the second provides an essential follow-up action (checking status). No redundant words, and the critical information is front-loaded. 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 no output schema, the description points to the status endpoint, implicitly suggesting the response contains a task ID, but does not explicitly define the return value. It covers the main flow (kick off duplication, then poll status) but could benefit from stating the response format or task ID. Given the tool's moderate complexity and lack of nested objects, this 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 all three parameters (suffix, workspace, collectionId) with clear descriptions. The tool description does not add additional meaning or examples beyond what the schema provides, so it meets the baseline for high schema coverage but contributes no extra 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 clearly states the action: 'Creates a duplicate of the given collection in another workspace.' It specifies the verb (creates), the resource (collection duplicate), and the destination (another workspace), distinguishing it from other collection-related tools like putCollection or getCollection.

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 follow-up instruction for checking task status but does not explicitly state when to use this tool versus alternatives or any exclusions. It implies use for duplication but lacks explicit guidance on when not to use it or what alternatives exist, such as copying within the same workspace.

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 convey openness (openWorldHint=true) and non-read-only nature (readOnlyHint=false), which the description aligns with via 'Creates a collection.' The description adds valuable behavioral context beyond annotations: the prerequisite constraint and the asynchronous polling-link response pattern. It could be enhanced by noting side effects or rate-limit concerns for this resource-creating operation, but the annotation disclosure is non-contradictory and sufficiently augmented.

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: first defines the action, second states the prerequisite, third describes the response. Front-loaded with the most important information and contains zero fluff or filler. This is a model of concise, value-dense description writing.

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 a moderately complex nested `options` object (9 sub-fields) and no output schema, the description does well to highlight the async nature via the polling link. The schema carries the full load on parameters, which it does thoroughly. A note on return type or error cases (e.g., what happens on invalid specId) could push this higher, but for the given scope, it's largely sufficient. The polling-link hint meaningfully compensates for the absent 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% across all 4 required parameters, so the baseline is 3, and the description adds no parameter-level details beyond what's in the schema. The description's mention of the spec existence requirement and the polling response is tangentially related but doesn't add new parameter semantics. With no param gaps in the schema, the description is not penalized further, but neither does it earn bonus credit — exactly 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?

The description clearly states the verb ('Creates'), resource ('collection'), and source ('from the given API specification'), which is specific and distinguishes it from sibling tools like `createCollection`. However, it doesn't explicitly contrast itself with siblings like `createCollection` or `syncCollectionWithSpec`, so it misses the full 5. The prerequisite note ('specification must already exist') adds useful scope definition.

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

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

The description provides clear context on when to use this tool: after a spec exists ('must already exist or be created before it can be used') and informs the agent about the async response behavior ('response contains a polling link to the task status'). However, it doesn't explicitly mention when NOT to use it or name alternatives, which would be needed for 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 indicate a mutating operation (readOnlyHint=false) but not destructive. The description adds that the response contains a polling link to task status, disclosing the asynchronous nature of the operation. This is valuable behavioral context beyond annotations, though it doesn't detail other side effects or permissions.

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 purpose, and no wasted words. It states what it does and mentions the asynchronous result link concisely.

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 5 parameters (all schema-documented) and no output schema, the description is mostly complete. It explains the main behavior and notes the polling link for status. It could mention prerequisites (e.g., collection must exist) but that is implicit and 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 the schema already documents all parameters. The description adds no new information about parameters beyond reinforcing the spec type via 'OpenAPI 2.0, 3.0, or 3.1'. Baseline of 3 is appropriate since 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?

The description clearly states the tool generates an OpenAPI specification (2.0, 3.0, or 3.1) for a given collection. It uses a specific verb+resource structure and differentiates from siblings like createSpec or generateCollection by focusing on the conversion from collection to spec.

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

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

The description implies usage (for a given collection) but does not explicitly contrast with alternatives or state when not to use it. It lacks the explicit when/when-not guidance seen in higher-scoring tools, though the context is reasonably clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the workspace scoping constraint but does not disclose pagination behavior, response format, or potential large result sets. Some value added, but limited beyond annotations.

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

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

One short, front-loaded sentence: 'Gets all API specifications in a workspace.' Every word earns its place, with no redundancy or filler.

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

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

For a simple read-only list tool, the description is mostly sufficient: full schema coverage, clear safety annotations, and a concise purpose. However, it lacks explicit pagination behavior (despite cursor schema) and alternative tool guidance, so it falls short of perfect 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 description coverage is 100% – all three parameters (workspaceId, limit, cursor) have clear descriptions. The tool description adds no additional parameter meaning, 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 clearly states 'Gets all API specifications in a workspace' – a specific verb ('gets'), resource ('all API specifications'), and scope ('in a workspace'). This distinguishes it from siblings like getSpec (singular) and getSpecFiles (files, not specs).

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

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

No guidance on when to use this tool versus alternatives. It doesn't mention using getSpec for a single spec or how pagination with limit/cursor works. With 35+ sibling tools, the lack of explicit usage context is a significant gap.

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 indicate read-only and idempotent behavior. Description adds no extra behavioral traits beyond clarifying the purpose; it does not mention side effects or permissions, but that is covered by 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?

Concise two-sentence description with a bullet point, no unnecessary fluff, and well-organized.

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 no parameters and no output schema, the description is sufficient. It explains what the tool does and when to use 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?

No parameters exist, so schema coverage is complete. Description need not add parameter details.

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 gets the authenticated user's information, with a specific verb and resource. The mention of fields (user.id, username, teamId, roles) further clarifies 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 when to use: when the user asks for 'my ...' to resolve the user ID. This is a strong usage guideline.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuinely useful behavior beyond that: the default return is a lightweight map rather than the full payload, and the full Postman response is opt-in. It omits any note on auth (though access_key is in the schema) or pagination/size limits.

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-loads the core action and default, then presents the opt-in variants as two tight bullets. Every sentence carries information; nothing is repeated from the title or schema verbatim.

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 describing return shape and does so for both the default map and the model variants. It is slightly thin on what 'recursive itemRefs' means in practice and says nothing about access_key behavior, but for a read-only single-resource getter it is nearly complete.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema lacks: model=minimal is spelled out as 'root-level folder/request IDs only' and the default (omitted) as a recursive itemRefs map, whereas the schema's enum text is vaguer ('Postman minimal model'). That is real added value over the structured field.

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

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

States a specific verb (Get) and resource (collection) and immediately names the default behavior (lightweight collection map with metadata + recursive itemRefs), which is what distinguishes it from the sibling getCollections. An agent can tell this retrieves a single collection and what shape it gets by default 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?

Gives clear guidance on how to use the tool: omit model for the default map, or opt in to minimal/full API responses. It does not name an alternative sibling (e.g. getCollections for listing) or state when-not-to-use, 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 declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds no behavioral details like return format or pagination, and the workspace requirement is already in the schema. Thus it adds minimal value beyond annotations.

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

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

The description is a single, focused sentence that directly instructs the LLM about the required parameter. It is concise, though it duplicates schema info slightly, it earns its place by instructing the agent to ask the user.

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 incomplete for a list endpoint: it does not state that it returns collections, nor mention any filtering or pagination behavior implied by the parameters. It focuses only on the workspace requirement, leaving the agent to infer the tool's function from its name.

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 all four parameters are documented. The description only restates that workspace is required, which is already in the schema; it adds no additional semantic 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 title states 'Get all collections' but the description only mentions the required workspace ID, not the tool's actual purpose. It does not explicitly say it retrieves collections, so the purpose is vague.

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 specific guideline about asking the user for the workspace ID if missing, but does not indicate when to use this tool versus alternatives like 'getCollection' or 'searchPostmanElements'. No exclusions or context for selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds nothing beyond that: no polling cadence, no indication of what terminal states look like, no auth or rate-limit 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?

A single front-loaded sentence with zero filler, which is structurally fine. But it is terse to the point of under-specification rather than genuinely concise, since it conveys nothing the name and title did not already convey.

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?

There is no output schema, so the description bears the burden of explaining what a status response contains (state values, progress, errors). It says nothing about return values, nor how the taskId is obtained, leaving the agent under-informed for a polling 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?

With one parameter at 100% schema description coverage, the schema already documents taskId as "The task's unique ID." The description adds no meaning beyond that, 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 clear verb and resource ("Gets the status of a collection duplication task"), so the basic purpose is legible. However, it is essentially a verbatim restatement of the tool title and name, adding no differentiating detail against siblings such as duplicateCollection (which presumably creates the task this tool polls) or getCollection.

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

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

No guidance on when to call this versus alternatives, no mention that the taskId originates from duplicateCollection, and no indication that this is a polling tool to be called repeatedly until completion. The agent must infer the entire workflow from the tool name.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond that: the response spans two distinct tool sets (full and minimal) and it should be invoked as a first step on failure. It does not detail the return shape, but the annotation bar is met.

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 IMPORTANT trigger and then the return-value explanation. Well-sized with no wasted text, though the title and first clause are mildly redundant with each other.

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?

No output schema exists, so the description must carry the return-value burden, and it does state that the response describes enabled tools across full and minimal sets. For a zero-parameter, read-only meta-tool this is adequately complete, though it leaves the exact response structure unspecified.

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 baseline of 4 applies. There is no parameter syntax for the description to clarify.

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 enabled tools') and clarifies what is returned: which tools are enabled in the full and minimal tool sets. This meta-tool is clearly distinguishable from the Postman domain siblings, which all operate on collections, specs, mocks, and workspaces.

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 an explicit trigger condition: 'Run this tool first when a requested tool is unavailable.' This tells the agent exactly when to reach for it and why (to find alternatives). It stops short of naming a specific alternative tool or a when-not-to-use case, but the conditional guidance is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description only says 'Gets information', which adds no extra context beyond what annotations state. It does not describe output format, potential error cases, or any additional behavioral traits, so it fails to add value beyond the structured metadata.

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

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

The description is a single short sentence with no fluff, making it concise. However, it is so minimal that it lacks substance; the sentence 'Gets information about an environment' is almost a tautology of the title. It is appropriately short but underdelivers on useful information, so a 3 is fair.

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 low complexity (1 param, no output schema), the description is too sparse. It does not hint at what 'information' is returned, nor does it mention any constraints like authentication scope. With no output schema, the agent is left guessing about the response structure. The description fails to round out the tool's context, so it scores 2.

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

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

The schema fully describes the single parameter environmentId, achieving 100% coverage. The description does not contribute any additional meaning, but the baseline for full coverage is 3. Since the tool is simple and the parameter is well-documented, a 3 is appropriate.

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

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

The description states the verb 'Gets' and resource 'environment', which is clear. However, it does not explicitly differentiate from sibling tools like getEnvironments (which likely lists environments) or hint that it retrieves a single environment by ID. The title and schema imply this, but the description itself lacks that distinction, so it scores 4.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention that getEnvironments is for listing or that this is for a specific environment. There is no context about prerequisites or typical API workflows, so the agent gets no 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds the scope (all environments) and links to docs, but doesn't disclose behavior like pagination, response format, or workspace filtering effects beyond 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?

One sentence with a helpful documentation link. No wasted words, front-loaded with the core 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?

For a simple read-only list tool with one optional parameter and full schema coverage, the description is adequate. It could mention that workspace is optional and what happens if omitted, but the schema already indicates it's not required. No output schema, but the tool name and description imply a list of environments.

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% (workspace parameter described as 'The workspace's ID.'). The description doesn't add extra meaning beyond the schema, but the schema is sufficient. 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 clearly states the tool gets information about all environments, with a link to documentation. It distinguishes from getEnvironment (singular) and createEnvironment, though it doesn't explicitly contrast with 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 implies usage for retrieving all environments, but doesn't provide explicit when-to-use vs alternatives. The optional workspace parameter suggests filtering, but no guidance on when to use this vs getEnvironment or getWorkspaces.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered by structured data. The description adds nothing beyond that — no note on what happens if no spec has been generated yet, no error behavior, no scoping caveats.

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

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

A single front-loaded sentence with no filler or repetition. It is efficient, though its brevity is closer to under-specification than to tightly packed 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 two-parameter, read-only tool with full schema coverage and clear annotations, the description is minimally adequate. With no output schema present, a sentence describing what the returned spec contains (or when generation must occur first) 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%, with both collectionUid and elementType documented in the schema (including the const value 'spec'), so the baseline of 3 applies. The description's phrase 'for the given collection' restates the collectionUid parameter without adding format, constraint, or example detail.

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

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

States a specific verb ('Gets') and resource ('the API specification generated for the given collection'), and the word 'generated' usefully distinguishes it from sibling readers like getSpec, getSpecDefinition, and getAllSpecs. It stops short of explicitly naming which sibling to prefer in which situation, so it is clear but not fully differentiated.

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?

There is no when-to-use guidance, no mention of prerequisites, and no reference to alternatives such as getSpec, getSpecDefinition, or generateSpecFromCollection, which occupy adjacent territory. The agent must infer from the name alone that this retrieves previously generated specs rather than raw ones.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds value by detailing response fields (collection UID and mockUrl) without contradicting any annotations. This gives the agent useful behavioral context beyond the structured metadata.

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

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

The description is concise and efficiently structured: a clear opening sentence and a bullet point for the response details. No filler or redundant information, and it is 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?

For a simple get operation with one parameter, the description, combined with annotations (read-only, idempotent) and schema (full parameter description), covers all necessary aspects: action, resource, response fields, and safety. The lack of an output schema is mitigated by the explicit mention of the returned 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 sole parameter mockId is fully described in the schema as 'The mock's ID,' covering 100% of the schema. The description does not add extra meaning to the parameter, but with complete schema coverage, 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 clearly states 'Gets information about a mock server,' specifying the action (gets) and the resource (mock server). It distinguishes from siblings like getMocks (plural) by focusing on a single mock entity, and it adds response details (collection UID, mockUrl) that clarify what information is returned.

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 context about the response, advising to use the collection UID for navigation, but it does not explicitly contrast with alternatives like getMocks or state when this tool should be selected. The purpose is clear enough to imply usage, but explicit selection criteria are missing.

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 annotations already declaring readOnlyHint, idempotentHint, and destructiveHint, the description adds valuable behavioral context: that it returns only servers the user created, and that workspace takes precedence over teamId. These nuances go beyond the annotations without contradicting them, covering key aspects like ownership filtering and parameter precedence.

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: a clear main sentence followed by three bullet points with actionable guidance. No redundant information or filler. Each sentence earns its place, effectively communicating purpose and usage in under 80 words.

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 list tool with two optional parameters, the description covers the essential aspects: what it returns (active mock servers, user-created by default), how to scope results, and parameter precedence. While it doesn't describe the response format or pagination, the tool's name and purpose make these implicit, and the annotations cover safety. This is adequate for the tool's complexity.

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 parameters documented. The description adds cross-parameter constraints and guidance (prefer workspace, how to set teamId from /me, and precedence rules) that enrich the schema's per-field descriptions. This goes beyond the baseline, providing actionable context for parameter selection.

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 all active mock servers, and specifies that by default it returns only the user's own mock servers across workspaces. This distinguishes it from siblings like getMock (singular) by explicitly focusing on listing multiple servers, and adds scope details that clarify its 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 explicit usage guidance: always pass either workspace or teamId, prefer workspace, and explains how to obtain teamId via GET /me. It also clarifies precedence when both are passed. However, it does not explicitly contrast with alternative tools (e.g., getMock for single server), so it falls short of full 'when-not' 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no additional behavioral details such as error handling or what 'information' is returned, but it does not contradict annotations.

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

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

The description is a single, front-loaded sentence with no wasted words. However, it is nearly redundant with the title 'Get a spec' and provides minimal additional 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?

With no output schema, the description is vague about what the return value contains. The tool is simple and annotations cover safety, but the description lacks enough detail to fully understand the tool's output, especially compared to sibling tools like getSpecDefinition.

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 covers 100% of the single parameter specId with a description. The tool description adds no extra meaning beyond the schema, 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 'Gets information about an API specification' clearly identifies a get operation on a spec resource. However, it does not differentiate between sibling tools like getSpecDefinition, getSpecFile, or getSpecCollections, making the purpose clear but not distinct.

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

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

No guidance is provided about when to use this tool versus the many sibling get tools. The agent is given no selection criteria or context for choosing getSpec 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the 'generated collections' scope but does not disclose pagination behavior, ordering, or response details beyond what the schema already suggests.

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

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

The description is a single, front-loaded sentence that directly states the tool's purpose with no filler or repetition. It is concise and every word contributes meaning.

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 rich annotations and a fully documented schema, the description is largely sufficient. The only minor gap is that 'all' is not reconciled with limit/cursor pagination, but the schema provides cursor and nextCursor guidance.

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 each parameter is already documented in the input schema, including the const value for elementType and cursor semantics. The description adds no additional parameter-level meaning beyond the schema, 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?

The description 'Gets all of an API specification's generated collections' has a specific verb, resource, and scope. It clearly distinguishes itself from siblings like getCollection (single collection) and getGeneratedCollectionSpecs (the reverse direction) by focusing on a spec's generated collections.

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

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

No guidance is provided about when to use this tool versus alternatives such as getCollections or generateCollection. The description simply states what the tool does without any context or exclusions.

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 indicate this is a read-only, idempotent, non-destructive operation. The description adds the scope 'complete contents' and the supported spec types (OpenAPI or AsyncAPI), but it does not disclose output format, error behavior, or any additional behavioral nuances.

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

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

The description is a single, front-loaded sentence with no filler or redundant wording. It communicates the essential action and resource efficiently.

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

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

This is a simple one-parameter read tool, and the annotations plus schema cover most important context. The description sufficiently states what is returned ('complete contents of a definition'), though it could be improved by clarifying how it differs from getSpec and getSpecFile.

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 'specId' with a clear description ('The spec's ID.'). The tool description adds no extra parameter-level information, so the schema carries the load and the 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 uses a specific verb ('Gets') and names the resource ('OpenAPI or AsyncAPI specification's definition'), making the core purpose clear. It does not explicitly differentiate itself from sibling tools like getSpec or getSpecFile, which introduces slight ambiguity.

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

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

There is no guidance on when to use this tool instead of alternatives. Given the many sibling tools that also deal with specs, the description provides no context or exclusions to help an agent choose correctly.

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 idempotentHint=true, so the safety profile is clear. The description adds no additional behavioral context beyond what the annotations provide, such as output format or error behavior. It does not contradict annotations, so a baseline score of 3 is appropriate.

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

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

The description is a single, short sentence: 'Gets the contents of an API specification's file.' It is front-loaded with the action and resource, contains no redundant words, and fully conveys the core purpose without any fluff. This is an exemplary model of conciseness.

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

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

The tool is simple (two parameters, no output schema), and the annotations cover safety. The description clearly indicates the tool retrieves file contents, which is sufficient for basic use. However, it does not specify the return format (e.g., raw text, JSON) or any path conventions, which could be considered a minor gap. Given the low complexity, the description 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%, and both parameters have descriptions in the schema: specId ('The spec's ID.') and filePath ('The path to the file.'). The description itself does not elaborate on parameter meaning or usage, so it adds no extra value beyond the schema. Baseline of 3 reflects that the schema handles parameter 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 states exactly what the tool does: 'Gets the contents of an API specification's file.' It uses a specific verb (Gets) and a clear resource (contents of a file within an API spec), which distinguishes it from siblings like getSpecFiles (listing files) and getSpecDefinition (specific definition). This is a clear, non-tautological 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 no guidance on when to use this tool versus alternatives. It does not mention that this is for a specific file's contents as opposed to listing files with getSpecFiles or retrieving the whole spec with getSpec. No exclusions or alternative tool references are given.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the 'all files' scope, but does not disclose return shape, pagination, error behavior, or whether file contents are included. It is adequate but not rich.

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

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

One short sentence with no redundant phrasing. It is front-loaded, scannable, and every word contributes to understanding the operation.

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 required parameter and strong annotations, the description is sufficient to convey the core operation. It does not describe the output format, but the absence of an output schema and the simplicity of the tool make this a minor gap rather than a critical omission.

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 specId is already documented in the schema with 100% coverage, so the description does not need to add much. It does reinforce that 'spec' refers to an API specification, but adds no syntax, format, or lookup details 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 uses a specific verb ('Gets') and resource ('all the files in an API specification'), clearly distinguishing it from the singular getSpecFile and related getSpec/getSpecDefinition tools. The 'all the files' scope adds precision beyond just the tool name.

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

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

The description implies usage when a caller needs all files belonging to a spec, but it does not explicitly name alternatives like getSpecFile or state when not to use this tool. The sibling tool names provide context, but the description itself offers no direct guidance.

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

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

尽管注解已声明 readOnlyHint=true，描述仍主动补充了关键行为：Enterprise plan 要求、各计划下的 404 错误行为，以及通过 tags 组织实体的语义。这种对失败场景的显式披露非常有价值。

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?

两段式结构清晰：首句突出企业版要求的警告，次句点明功能。所有企业版后续处理需求都在描述中，没有冗余信息。略失分在于缺少一个最终总结或示例。

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?

在注解和 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?

模式覆盖率为 100%，所有五个参数（slug, limit, cursor, direction, entityType）在 schema 中都有详细描述。描述本身未添加参数语义，但 schema 已足够完整、自解释，因此维持基线 3 分。

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

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

描述明确使用动词 "Gets" 和资源 "Postman elements by a given tag"，并补充了'organize and search workspaces, APIs, and collections'的场景说明。虽然未显式区分兄弟工具，但资源范围清晰，足以让 agent 理解核心功能。

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?

明确指出需要 Enterprise plan 及非企业版返回 404 的关键约束，这是重要的触发条件。但未提供何时选择其他兄弟工具（如 searchPostmanElements）的指导，也没有说明与按标签筛选、按关键词搜索等替代方案的区别。

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, idempotentHint=true, and destructiveHint=false, indicating a safe read operation. The description adds valuable context about the 'visibility' field, explaining its possible values, access implications, and plan restrictions. This enriches the behavioral understanding beyond the bare 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 core purpose is stated in a single sentence, but the description then expands into a lengthy, detailed explanation of the visibility field with sub-bullets and multiple links. While informative, this makes the description longer than necessary for a simple GET tool and could have been condensed without losing essential information.

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

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

The tool is a straightforward GET with two parameters and no output schema. The description explains one field (visibility) but does not provide an overview of other typical workspace properties returned. Given the simplicity and annotation coverage, the description is adequate but could have briefly summarized the general response structure to be more 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%, and the parameter descriptions in the schema are clear (workspaceId and include). The tool description does not add any extra meaning to the parameters; it only discusses the visibility field in the response. With full schema coverage, 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 states 'Gets information about a workspace' with a clear verb and resource, which is unambiguous. However, it does not explicitly distinguish it from sibling tools like getWorkspaces (which lists multiple workspaces), relying on the singular/plural name difference. The main body focuses on the visibility field, which is additional but not primary purpose elaboration.

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?

There is no guidance on when to use this tool versus alternatives. It does not mention when to call getWorkspace instead of getWorkspaces, nor does it describe any prerequisites or context for use. The description is purely about the visibility field semantics, not about usage scenarios.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: it explains the visibility field and its values, which affects what the agent can infer about access control. It also mentions pagination behavior and the need to call /me first for user-scoped queries. This adds context beyond the annotations, though it doesn't describe the full response structure (no output 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?

The description is well-structured with bullet points and examples, making it easy to scan. It's a bit long but each section adds value: purpose, visibility explanation, usage notes, pagination, and examples. The front-loading is good (purpose first), and the examples are concrete. It could be slightly more concise, but the detail is justified given the tool's complexity.

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 complexity (7 parameters, no output schema, no required parameters), the description is quite complete. It covers the main use cases, explains the visibility field, provides examples, and mentions pagination. The only gap is that it doesn't describe the response structure, but since there's no output schema, the agent might need to infer that. However, the description does mention the 'meta.nextCursor' field, which gives some response context. Overall, it's sufficient for an agent to use the tool effectively.

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 7 parameters. The description adds value by explaining the 'createdBy' parameter's role in 'my …' requests and providing examples of how to combine parameters (e.g., type=personal&createdBy=...). It also clarifies the 'type' parameter's behavior when not specified. This goes beyond the schema's basic descriptions, though the schema already covers the parameter meanings well.

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: 'Gets all workspaces you have access to.' It specifies the resource (workspaces) and the action (get), and distinguishes it from sibling tools like getWorkspace (singular) and createWorkspace by focusing on listing/filtering workspaces with user-scoping.

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

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

The description provides explicit usage guidance: it explains when to call GET /me first for 'my …' requests, how to handle missing workspace IDs, and includes concrete examples for different scenarios. It also mentions pagination with cursor, which is a clear usage instruction. This goes beyond just stating the purpose and helps the agent decide 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?

The description discloses the side effect of setting Access Control to public, which is a meaningful behavioral detail beyond the annotations that only indicate mutability. It does not contradict 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, with two sentences: one for the primary action and one for the key side effect. 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?

The description provides sufficient context for a simple operation: it states what it does and the main effect (setting access control to public). It does not mention return values, but no output schema exists, and the information given is adequate for the tool's purpose.

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

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

The schema already fully describes the mockId parameter with 'The mock's ID.' The description adds no additional parameter-specific meaning, so 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 action: 'Publishes a mock server.' The verb 'publishes' and resource 'mock server' are specific, and the tool is distinguishable from siblings like createMock or getMock.

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

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

The description implies usage when you want to make a mock public (by setting access control to public) but does not explicitly state when to use this tool vs alternatives or provide exclusion 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 description supplies genuinely useful behavioral detail beyond the annotations: a 100 MB size cap, a 202 Accepted async path, and the consequence that omitting item IDs removes and recreates items with new IDs. However, that same text sits in tension with the structured hints — 'removes the existing items' is not an additive update (destructiveHint: false) and recreating items with fresh ID values makes repeat calls observably non-identical (idempotentHint: true). Because the description conflicts with the annotations on those points, it cannot be scored at or above baseline, though the conflict is narrower than a flat read/write reversal, so 2 rather than 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 core operation is front-loaded and the bulleted structure is scannable, but there is real redundancy: the ID-removal warning appears in the opening paragraph and again as a Note bullet, and the same Collection Format docs URL is linked twice. Trimming the duplicated warning and link would tighten it without losing 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 complex nested-payload mutation with no output schema or annotation coverage of the payload, the description covers size limits, the async flow and its status endpoint, ID-preservation semantics, and the cross-collection copy pitfall. It still omits permission/auth prerequisites and whether the replacement is atomic on failure, which would matter to an agent deciding whether to call 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?

Schema description coverage is 100%, so the baseline is 3, and the description earns more by explaining semantics the schema does not: the body must follow the Postman Collection v2.1.0 schema, collection ID values must be carried in the body, and which ID fields (id, uid, postman_id) must be stripped before reusing another collection's payload. It adds real meaning on top of the structural schema rather than restating it.

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 first sentence gives a specific verb and resource ('Replaces the contents of a collection') plus the required payload format (Postman Collection v2.1.0). An agent can tell this apart from createCollection or updateCollectionRequest by the plain-language 'replace the contents' framing. It stops short of naming a sibling explicitly, so it does not reach the top of the scale.

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 actionable conditional guidance: send the Prefer: respond-async header for async updates, poll GET /collection-updates-tasks/{taskId} for status, and strip id/uid/postman_id values when copying another collection or the call errors. What is missing is explicit routing away from siblings (e.g. when to call updateCollectionRequest or createCollection instead), so it is clear context rather than full when/when-not 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 description adds useful operational details such as the 30MB request limit, the 411 Content-Length workaround, and the shared-variable limitation. However, it contradicts the annotations: destructiveHint is false while 'Replaces all the contents' describes a destructive overwrite of existing environment 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?

The description is concise and well-structured: one purpose sentence followed by three focused note bullets. Each bullet adds operational value, and there is no redundant or filler 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 write tool with no output schema, the description covers replacement semantics, body size limits, error handling, and the shared-variable API constraint. It lacks explicit return-value information and prerequisites, but the rich schema and annotations compensate for most gaps.

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

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

The input schema has 100% schema_description_coverage and rich descriptions for every parameter and nested property. 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 first sentence uses the specific verb 'Replaces' with the resource 'environment' and scope 'all the contents', making the operation unmistakable. It clearly distinguishes this from sibling tools like createEnvironment or getEnvironment.

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

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

The description implies usage for overwriting an existing environment's data, but it does not explicitly state when to use this tool versus createEnvironment or any other alternative. No exclusions or preferred conditions are given.

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 destructiveHint=true and openWorldHint=true, so the safety profile is partly covered, yet the description never acknowledges that executing a collection fires real requests against external systems. It does add useful context the annotations do not: what the run returns (test results, execution statistics) and which runtime knobs are unsupported.

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 tight sentences that front-load the core action and its output before the environment note and limitation. Every sentence carries information, with only minor redundancy between 'detailed test results' and 'execution statistics'.

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 correctly steps in to describe the return payload, and it flags a capability gap. However, for a tool annotated destructive and open-world, it omits permission requirements and the side effects of actually executing collection requests, leaving an important behavioral hole.

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% across all 9 parameters, so the schema already documents collectionId, environmentId, timeouts, and the stop/abort flags with defaults. The description only reinforces environmentId and notes missing delay options, adding little beyond the structured fields; 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 (Runs) and resource (Postman collection) plus the identity input (by ID) and what it produces (test results and execution statistics). It is clearly distinguishable from read-only siblings like getCollection and from generateCollection, though it never names an alternative to route against.

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?

There is no guidance on when to choose this over siblings such as getCollection, generateCollection, or duplicateCollection. The only usage-shaped content is a negative constraint ('advanced parameters ... not yet available'), which tells the agent what it cannot do rather than when to reach for it.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds behavioral scope semantics the annotations do not: the default ownership=organization restricts to your org versus external/public-network search, which materially changes result set. It stops short of describing pagination 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?

Front-loaded with purpose, then cleanly sectioned into ownership, element types, and filters with tables and examples. Some redundancy: the entityType and ownership definitions are restated nearly verbatim from the schema, which inflates length without adding new 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 6-parameter search tool with nested filter objects and no output schema, the definition covers scoping, element types, and filter syntax thoroughly. The one gap is that neither the description nor annotations explain result shape or how cursor pagination interacts with limit, though the schema documents the cursor field itself.

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 baseline is 3, but the description adds semantics the schema does not encode: which element types each filter field is valid for (method = requests only, tags = workspaces/collections only) and worked filter-expression examples. That is genuine value beyond the schema's structural constraints.

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 (search) and enumerates the exact resource types it operates over (requests, collections, workspaces, specs, flows, environments, mocks, documents). An agent can distinguish this aggregate search tool from the many narrow getters in the sibling list (getCollections, getWorkspaces, getSpec) immediately.

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 ownership table maps concrete user intents ("our notification service", "Stripe API", "our APIs") to specific parameter values, and the filter field table states which element types each filter applies to. This is explicit when-to-use guidance with alternatives, not 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 description discloses the async behavior: 'This is an asynchronous endpoint that returns an HTTP 202 Accepted response.' This goes beyond the annotations and informs the agent that success is not a completed sync. It also adds restrictions around supported spec types and the generation relationship, though it does not mention how to track or confirm the async completion.

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

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

The description is short, front-loaded, and uses bulleted notes for detail. Every sentence serves a purpose: defining the operation, flagging async behavior, and listing key constraints. No redundant text or padding.

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 an operation with simple parameters and no output schema, the description is sufficiently complete: it covers purpose, async behavior, supported spec types, and a required relationship with the passed spec ID. It lacks an explicit statement about what happens after the 202 response or whether a separate status-check tool is needed, but this is 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?

The input schema already describes both parameters clearly with 100% coverage. The description adds meaningful context by saying 'You can only sync collections generated from the given spec ID,' which clarifies the relationship between specId and collectionUid. It also implies that collectionUid should be a collection generated from specId.

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

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

The description clearly states the action: 'Syncs a collection generated from an API specification.' It identifies the resource (a collection) and the operation (sync), and clarifies the spec types supported. However, it does not explicitly distinguish this tool from its sibling syncSpecWithCollection, so sibling differentiation is weaker.

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 some usage context: the tool is for collections generated from specs, supports only OpenAPI 2.0/3.0/3.1, and can only sync collections generated from the given spec ID. But it does not explain when to choose this over alternatives like syncSpecWithCollection or when not to use it.

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

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

Annotations already indicate a non-read-only, idempotent, non-destructive operation. The description adds valuable behavioral context beyond this: it explicitly states the endpoint is asynchronous and returns HTTP 202 Accepted, and further constrains the operation to specific OpenAPI versions and collection origins.

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 plus a short bulleted list. It front-loads the core action and then efficiently presents the key constraints. No redundant words.

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 tool with no output schema, the description covers the essential invocation context: async behavior, supported spec types, and a precondition on the collection. It does not explain what the sync actually updates or how to poll for completion, but this is moderately covered by the annotations and the tool's purpose.

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 clear descriptions for both parameters, so baseline is 3. The description adds semantic linkage between specId and collectionUid by stating that only collections generated from the given spec ID can be synced, which clarifies how the parameters relate and what values are valid.

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 action ('Syncs an API specification linked to a collection') with a clear subject and resource. The direction (spec to collection) is implied by the constraint that only collections generated from the spec ID can be synced, which distinguishes it from the sibling syncCollectionWithSpec, though not explicitly.

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

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

The description includes important usage constraints: it is asynchronous, supports only OpenAPI 2.0/3.0/3.1, and requires collections generated from the given spec ID. However, it does not explicitly mention when to use this tool versus the reverse sibling syncCollectionWithSpec, nor does it provide alternative suggestions.

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 cover readOnly=false, destructive=false, idempotent=true, so the safety profile is set; the description still adds substantial non-obvious behavior: omission keeps stored values, folder changes are unsupported, and events are merged by `listen` type with the `events: []` no-op gotcha. This is precisely the context an agent needs.

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-loads the core purpose in one sentence, then uses a scoped note with bullets for the exceptions. The link to the Request schema and the bullets all earn their place, though it is slightly verbose.

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 15-param partial-update tool with full schema description coverage and no output schema, the description covers the key behavioral nuances (partial semantics, folder limitation, events merging). Only the absence of return-value or auth expectations keeps it from being fully 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, but the description adds real meaning beyond the schema: the warning that a collection ID (not a collection) must be passed addresses the ambiguous `collectionId` param, and the `events` merge semantics are explained in depth.

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 ('Updates a request in a collection'), which clearly separates it from createCollectionRequest and other siblings. It lacks an explicit contrast, but the scope is unambiguous.

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

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

Implies when to use it via the PATCH-like note ('only updates the values that you pass'), which tells an agent it is a partial update. However, it never names an alternative or states when-not-to-use this tool versus createCollectionRequest, so guidance stays implicit.

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 that this is a mutating but non-destructive, idempotent operation. The description adds useful behavioral detail by explaining how setting `config.serverResponseId` activates a server response and passing `null` deactivates it. It does not contradict 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, uses bullet points for scannability, and front-loads the core purpose. Every line carries useful information: the resource, the actionable fields, and the special activation behavior. There is no redundant 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 two-parameter update tool with a fully documented schema and annotations covering safety and idempotency, the description provides the essential operational context. It explains what can be updated and the key behavioral nuance for `serverResponseId`, making it complete enough for an agent to select and invoke 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 all parameter meanings. The description's activation/deactivation note largely repeats the schema text for `serverResponseId`, adding no significant semantic information beyond what the schema provides. This meets the baseline but does not exceed it.

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 action ('Updates a mock server') and a specific resource ('Mock server entity associated with a collection UID'). It also enumerates the fields that can be changed, making its purpose clear and distinct from creation, publishing, or other mock-related operations.

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 'Use this to change name, environment, privacy, or default server response,' which gives clear when-to-use guidance. It does not explicitly mention alternatives or exclusions, such as pointing to createMock or publishMock, so it falls short of full 5-level 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 indicate a write operation (readOnlyHint=false, destructiveHint=false), but the description adds valuable behavioral details: no empty body, cannot pass multiple body properties, root file switching behavior, and file size limit. This covers important side effects and constraints beyond the annotations, improving transparency.

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 highly concise, front-loading the purpose and then using bullet points for critical notes. No superfluous text; every sentence 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?

Given the tool's complexity and lack of output schema, the description covers essential constraints (no empty body, no multi-property, root-file behavior, size limit) that are critical for correct usage. It does not explicitly address error conditions, but the provided notes are substantial enough for a complex mutation 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 covers all 5 parameters at 100%, so baseline is 3. The description adds cross-parameter constraints (cannot pass both content and type simultaneously) and explains the root file behavior, which enriches the parameter semantics beyond individual field descriptions.

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

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

The description clearly states it updates a spec file for OpenAPI or protobuf, using a specific verb+resource. It implicitly distinguishes from createSpecFile (updating vs creating), though it doesn't explicitly name alternative tools. The title and description align well.

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 context on when to use (updating existing spec files) but does not explicitly mention when not to use it or contrast with sibling tools like createSpecFile or updateSpecProperties. The constraints (no empty body, one property at a time, root file rules) are helpful but are more about how to use than when.

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 no behavioral context beyond what the annotations already convey. Annotations indicate the operation is not read-only, not destructive, and idempotent, but the description does not mention permissions, side effects, or what happens to unspecified properties. There is no contradiction with annotations, but there is also no added transparency.

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

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

The description is a single focused sentence with no wasted words. It is front-loaded with the verb and object, making it easy to scan.

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 update operation with complete schema coverage, the description is minimally adequate. However, it does not clarify the update's scope (e.g., whether only metadata like name is affected, versus file contents or definition), nor does it mention return or failure behavior.

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 clearly documented. The description's mention of 'such as its name' only repeats the schema's existing parameter description and adds no meaningful semantic detail, 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 clearly states the action ('Updates an API specification's properties') and gives a concrete example ('such as its name'). This distinguishes it from sibling tools like updateSpecFile or updateWorkspace by focusing on spec property metadata.

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

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

No guidance is provided about when to use this tool versus alternatives like updateSpecFile, createSpec, or putSpec. The description only restates the basic action without any context, exclusions, or relationships to other 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 cover read-only, destructive, and idempotency hints, so the remaining burden is added context. The description contributes meaningful behavioral details: unsupported visibility changes by plan/audience, rate limits when publishing public workspaces, and a uniqueness requirement for public team workspace names.

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 opening sentence is concise and specific, and the note list is scannable. There is minor redundancy with the schema's type field description, but the additional notes earn their place and clarify failure modes.

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?

Combined with the rich schema and annotations, the description covers the key failure modes and constraints for an agent making a workspace update. It does not describe the response shape, but the main risks for this operation are behavioral and are disclosed here.

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 description is not required to restate field definitions. It adds value with parameter-level constraints, especially the uniqueness rule for public team workspace names and rate-limit implications when setting public visibility.

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

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

The description uses the specific verb 'updates' with a workspace resource and gives concrete examples such as name or visibility. It clearly distinguishes the tool from sibling read/create operations without being a tautology of the title.

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

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

The description implies the tool is for modifying an existing workspace and gives important constraints such as unsupported visibility transitions, rate limits, and unique public team names. It does not explicitly direct agents to choose this tool over alternatives like createWorkspace or getWorkspace, so the guidance is present but not proactive.

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