portkey

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

The annotations only provide destructiveHint=true, so the description carries the burden of explaining how the mutation behaves. It adds that feedback is attached by trace_id, includes the quality-score semantics, and identifies the underlying HTTP POST endpoint. It does not discuss overwrite/idempotency or auth, but for a create operation this is sufficient additional behavioral context.

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

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

Two short sentences plus an endpoint string, with the primary action 'WRITES' front-loaded. Every sentence carries meaning and there is no filler.

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

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

For a 4-parameter write operation with no output schema, the description gives the use case, parameter ranges, attachment mechanism, and the POST endpoint. It omits return-value details and error behavior, but this is a simple create action and the provided context is likely sufficient for correct invocation.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description repeats the value range (-10..10) and optional weight (0..1) and metadata, adding little beyond the schema; it slightly clarifies trace_id's role as the attachment target, but that is also in the schema.

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

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

The description opens with 'WRITES a feedback record into the Portkey account', naming a specific verb, resource, and attachment target. It clearly distinguishes this from all sibling get/list tools, which are read-only retrieval 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?

It explicitly says to use the tool 'for logging a quality score' with optional weight and metadata, which gives concrete invocation context. It does not explicitly name alternatives or exclusions, but the sibling set is entirely retrieval tools, so the intended use is clear enough.

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

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

The description's 'Get' verb and the 'Portkey: GET /analytics/graphs/{metric}' endpoint align with the readOnlyHint annotation, so there is no contradiction. It does not disclose details like auth requirements, rate limits, or response shape, but the read-only behavioral safety is already carried by the annotation.

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

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

Three concise sentences, with the core purpose front-loaded. The metric examples and endpoint reference are useful and earn their place; there is no redundant or filler phrasing.

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

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

For a 7-parameter read-only tool with 100% schema coverage and no output schema, the description plus schema gives an agent enough to call it correctly. It could be slightly stronger by noting how it differs from portkey_get_analytics_group or by hinting at the graph response format, but nothing critical is missing.

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

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

Input schema description coverage is 100%, so all parameters are already documented structurally. The description adds a readable summary of the metric types and optional scoping fields, but it does not add meaningfully new syntax, defaults, or usage constraints beyond what the schema supplies.

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 ('Get a time-series analytics graph'), a specific resource ('single metric... over a time window'), and optional scoping dimensions. It is clear and informative, but it does not explicitly differentiate itself from the closely related sibling portkey_get_analytics_group.

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

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

Usage context is implied: use this for a single-metric time-series graph with optional filtering. However, there is no explicit when-to-use vs alternatives guidance, and the related analytics sibling tool is never mentioned or ruled out.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the endpoint and clarifies aggregation modes and time-window filtering, but does not disclose response format or pagination defaults; this is acceptable given the read-only annotation.

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

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

Two sentences with no filler. The core action and grouping dimensions are front-loaded, and the endpoint reference adds useful context without redundancy.

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

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

For a read-only analytics list-like tool with full parameter documentation and a readOnlyHint, the description is largely sufficient. No output schema exists, but the behavior is simple enough that an agent can invoke it correctly based on the provided description and schema.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds minimal extra meaning beyond restating grouping dimensions and the time window, which is fine but not compensating for any schema gaps.

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 states a clear verb and resource: 'Get grouped analytics', with the grouping dimensions explicitly listed. It is unambiguous, but it does not differentiate from the sibling tool portkey_get_analytics_graph, so it lacks explicit sibling differentiation.

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

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

No guidance is provided on when to use this tool versus portkey_get_analytics_graph or other sibling tools. The description gives the endpoint but no selection criteria 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 declare readOnlyHint=true, so the read-only nature is covered. The description adds a valuable behavioral detail beyond the annotation: the secret is never returned, which sets accurate expectations about the response and privacy boundary. This is meaningful supplementary disclosure.

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 contain all essential information with no filler. The primary action is front-loaded, and the API endpoint reference is a compact, useful addition. 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 simple single-get operation with one required parameter, a readOnly annotation, and no output schema, the description provides enough context: what is returned (metadata) and what is not returned (secret). The absence of a richer return-shape description is a minor gap but not a blocker for correct invocation.

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

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

Schema description coverage is 100%, and the parameter 'id' is documented as 'The API key id.' The description only adds 'by id', which reinforces the parameter's role but does not add format, source, or constraints beyond the schema. With full schema coverage, a baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Get a single API key's metadata by id'. It clearly differentiates from sibling list tools like portkey_list_api_keys by specifying 'a single' key identified by id, and the extra note that the secret is never returned adds important precision.

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

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

The description clearly indicates this tool is for retrieving one API key's metadata by id, which is a clear context for use. It does not explicitly name alternatives or state when not to use it, but the single-by-id framing makes the appropriate usage unambiguous.

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

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

The readOnlyHint annotation already covers the safety profile, and the description adds the REST endpoint and the fact that routing rules are included. No further behavioral details (errors, auth, rate limits) are provided, but the bar is lower because annotations are present.

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

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

Two sentences with no filler. The core behavior and identifier are front-loaded, and the API reference is a compact addition that helps ground the tool in the underlying service.

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

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

For a single-parameter read tool with a readOnly annotation and no output schema, the description provides the essential information: what is retrieved, how it is identified, and what is included. A note on return format would be nice but is not critical 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% and the schema already describes the slug parameter. The description's 'by slug (or id)' mirrors the schema rather than adding new meaning, so it stays at the baseline.

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

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

The description states a specific verb ('Get'), a specific resource ('single gateway config'), and the identifier ('by slug or id'). Mentioning 'including its routing rules' adds meaningful detail and 'single' clearly distinguishes this from list-style sibling tools.

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

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

The description makes it clear this tool is for retrieving one specific config by slug or id, which implies the opposite of list_configs. However, it does not explicitly name alternative tools or provide when-not-to-use guidance.

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

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

The readOnlyHint annotation already covers the safety profile, so the description does not need to restate it. The description adds the concrete HTTP endpoint 'GET /users/{id}', which is useful, but discloses no additional behavior such as error handling, response shape, or auth requirements. This is acceptable for a simple read-only resource fetch.

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 tight sentence that states the operation, the scope, and the endpoint. There is no filler, and every part contributes to correct invocation.

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

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

For a one-parameter, read-only, simple fetch operation, the description is sufficient: it identifies the action, resource, and endpoint. It could go further by describing response format or not-found behavior, but these are minor gaps and no output schema exists to clarify them.

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 covers the single 'id' parameter at 100% coverage with its own description, so the baseline is 3. The description only restates 'by id' and adds no new semantic detail beyond what the schema already provides.

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

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

The description explicitly states the action ('Get') and the resource ('a single user by id'), making the tool's purpose unambiguous. It naturally distinguishes itself from sibling list tools like portkey_list_users by emphasizing the singular scope.

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

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

The phrase 'a single user by id' clearly establishes when to use this tool: when the agent has a specific user id and needs that one user, rather than a collection. It does not explicitly name alternatives or exclusions, but the context is clear enough for correct 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 mark readOnlyHint=true, and the description reinforces this by stating 'GET /virtual-keys/{slug}', making the HTTP method and read-only nature explicit. It adds useful behavioral context by noting the response includes provider and limits, though it does not cover error/edge-case behavior.

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

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

Two short sentences are front-loaded with the core behavior before the endpoint reference. Every phrase earns its place, with no verbose repetition of the title or schema.

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

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

For a one-parameter read-only lookup, the description provides the resource, the lookup identifier, and the main response content (provider + limits). With annotations covering safety and no output schema required, it is reasonably complete, though exact error behavior is left 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 schema already fully documents the only parameter, slug, at 100% coverage. The description repeats the slug lookup concept without adding format, constraints, or usage detail beyond the schema, so the baseline score of 3 applies.

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

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

The description opens with a specific verb ('Get'), a precise resource ('single virtual key'), and the lookup key ('by slug'), and names the response highlights ('provider + limits'). 'Single' clearly distinguishes it from the sibling list_virtual_keys tool.

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

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

The phrasing 'a single virtual key by slug' establishes the context for fetching one specific key, implicitly contrasting with list_virtual_keys for multiple keys. It does not explicitly name alternatives or exclusions, so it stops short of the strongest guidance.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds the API endpoint and clarifies the lookup is by slug or id, but it does not mention potential errors or response behavior. With annotations covering the safety profile, this is adequate.

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

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

The description is extremely concise: one sentence states the operation and identifier type, and the second gives the exact endpoint. There is no wasted text, and the core behavior is front-loaded.

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

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

For a simple single-parameter read-only get operation with full schema coverage and no output schema, the description is complete. An agent has everything needed 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 coverage is 100%, with the id parameter already described as 'The workspace slug or id.' The description repeats this information without adding meaningful new detail, so the schema carries the semantic weight.

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

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

The description clearly states the tool's purpose: retrieving a single workspace identified by slug/id. This distinguishes it from sibling tools like portkey_list_workspaces, which retrieve multiple workspaces, and from other get_* tools targeting different resources.

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

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

The phrase 'single workspace' and the slug/id parameter clearly indicate this tool is for one specific workspace, implicitly contrasting with list tools. However, it does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context by stating that secrets are never returned. This reassures the agent that the operation is safe and does not expose sensitive key material. The HTTP endpoint reference adds minor extra 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 two concise sentences, front-loads the core purpose and scope, and includes the safety-relevant metadata-only note. Every word earns its place with no redundancy.

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

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

For a simple list operation with three optional pagination/scope parameters and no output schema, the description covers the essential behavior, scope, and secrecy guarantee. It does not describe the exact response shape, but 'metadata only' plus the schema's pagination fields provide sufficient context for calling 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%, with each parameter already documented in the schema. The description does not add significant parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description names the specific action ('List API keys') and resource scope ('organization/workspace'), and adds a key distinguisher: metadata only, secrets never returned. This clearly separates it from siblings like get_api_key (single key) and list_virtual_keys (virtual keys).

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 useful context about scope ('organization/workspace') and the metadata-only nature, so an agent can infer when it is appropriate. However, it does not explicitly mention when to prefer an alternative such as get_api_key or list_virtual_keys, leaving some selection logic to inference.

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

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

The annotation readOnlyHint=true already communicates that this is a read operation, and the description's 'GET /audit-logs' reinforces that with no contradiction. It does not add much beyond the annotation, such as auth requirements, rate limits, or response-shape notes, so it provides only modest extra behavioral context.

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

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

Two compact sentences lead with the action and resource, then give the scope and endpoint. There is no filler, and the most decision-relevant information is front-loaded.

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

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

For a simple paginated list tool, the description plus schema covers what the tool returns, its organizational scope, its read-only nature, and pagination inputs. No critical information an agent needs to select and invoke it is missing.

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

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

Both parameters (page_size, current_page) have descriptive schema entries, so the schema carries the load for parameter meaning. The description adds no additional parameter semantics, matching the baseline for high schema coverage.

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

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

The description uses a specific verb ('List') plus a specific resource ('audit log entries') and clarifies the scope ('admin actions across the organization'), making it easy to distinguish from sibling list tools such as portkey_list_users or portkey_list_api_keys. It also identifies the underlying endpoint, removing ambiguity.

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

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

The phrase 'admin actions across the organization' gives a clear context for when this tool is relevant, but it does not explicitly state when to prefer it over a sibling or mention any exclusions. There are no alternatives named, so the guidance is clear but not fully explicit.

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

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

The readOnlyHint annotation already establishes this is a safe, non-mutating operation. The description adds the underlying endpoint (GET /configs) and clarifies the domain of configs, but it does not mention pagination, result shape, or any other behavioral caveats. This is acceptable 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?

The description is a single, front-loaded sentence that states the action, the object, and a clarifying definition. Every clause earns its place, and the endpoint reference is compact and useful.

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

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

For a simple read-only list tool with one optional, fully documented parameter and no output schema, the description is complete. It explains what the tool returns conceptually and identifies the associated API endpoint, and the readOnlyHint annotation covers the safety profile.

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 schema already explains workspace_id as 'Scope configs to a workspace id/slug.' The description does not add parameter-level detail, but it does not need to because the schema carries the full semantic load.

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 ('List') and a resource type ('gateway configs'), adding a parenthetical that clarifies configs as routing/fallback/retry/cache rulesets. This clearly distinguishes the list operation from singular sibling tools like portkey_get_config.

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

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

The description makes clear that this tool lists configs, and the schema explains the optional workspace scoping. However, it does not explicitly state when to prefer this over alternatives such as portkey_get_config, nor does it mention any exclusions or prerequisites.

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

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

The annotations already declare readOnlyHint=true, so the description correctly aligns with a read operation. It adds useful context by specifying that only 'pending' invites are shown and that they are scoped to the organization. However, it discloses nothing about pagination defaults, ordering, or authorization, so it is just adequate beyond the annotations.

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

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

The description is a single informative sentence plus an endpoint reference, with no filler. It is front-loaded with the core action and resource, making it easy to scan and every word 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 simple read-only list operation, the description plus schema and annotations cover what an agent needs: the resource, the pending filter, the pagination parameters, and the safety profile. Without an output schema, no return-shape detail is required, and there are no complex behaviors left undocumented.

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 documents both parameters (page_size and current_page) with defaults and descriptions, giving 100% schema coverage. The description itself adds no parameter-specific meaning, so it relies entirely on the schema, matching the baseline score.

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

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

The description clearly states a specific action ('List'), a specific resource ('pending user invitations'), and scope ('to the organization'), and it names the exact endpoint. This distinguishes it from sibling tools like portkey_list_users, which target existing users rather than invitations.

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 resource name and intent ('List pending user invitations') imply when to use it, but there is no explicit guidance about when not to use it or which sibling tool should be chosen for similar needs. It neither mentions alternatives nor exclusion criteria, so usage context must be inferred.

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

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

The readOnlyHint annotation already establishes the read-only nature. The description adds the concrete HTTP context, 'Portkey: GET /users,' which reinforces that this is a safe read operation. No side effects or destructive behavior are implied.

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

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

The description is two short, front-loaded sentences and an endpoint hint. Every sentence earns its place with no filler or redundant wording.

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, the description plus the fully documented schema is sufficient for correct invocation. It does not describe the return format, but the intent is clear and pagination is inferable from the parameters.

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

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

Schema coverage is 100%, so the parameter descriptions already carry most of the meaning. The description adds a useful summary of role and email filters but does not add meaningful detail beyond what the schema provides for pagination parameters.

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

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

The description clearly states the verb and resource: 'List users in the organization' and identifies the two main filters. It is distinct from siblings like portkey_get_user and portkey_list_workspace_members, but it does not explicitly contrast itself with them.

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

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

The description implies the tool is for listing organization users, optionally filtered by role or email. It gives clear context but provides no explicit guidance on when to choose this over sibling tools such as portkey_get_user or portkey_list_workspace_members.

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

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

Annotations declare readOnlyHint=true, and the description adds context about what the virtual keys represent and the REST endpoint. It does not disclose additional behavioral details beyond the annotation, but for a simple read-only list operation this is sufficient.

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 front-loads the action and then provides a clarifying definition and endpoint. There is no filler or redundancy.

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

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

For a simple read-only list tool with two optional pagination parameters and no output schema, the description covers the essential purpose and object semantics. It might optionally mention that it returns a paginated list, but the schema already documents pagination, so nothing critical is missing.

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

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

Schema description coverage is 100%, with both parameters (page_size and current_page) already documented with defaults and types. The description adds no parameter-specific detail, 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 states a specific verb and resource: 'List virtual keys', and elaborates with a parenthetical definition of what virtual keys are (aliases mapping to provider credentials plus budget/rate limits). This clearly distinguishes it from sibling tools like portkey_get_virtual_key (singular) and other list tools.

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

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

The usage context is implied by 'List virtual keys' — an agent can infer this is the tool to call when enumerating virtual keys. However, there is no explicit guidance on when to choose this over alternatives such as portkey_get_virtual_key, nor any exclusions or prerequisites.

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

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

The readOnlyHint annotation already covers the safe read-only nature of the tool. The description adds the HTTP GET endpoint and clarifies the returned content includes users and roles, but it does not describe response shape or pagination behavior beyond what the schema already provides.

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

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

The description is two short sentences with no filler. The core purpose is front-loaded, and the endpoint reference provides immediate technical clarity without unnecessary detail.

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

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

For a low-complexity listing tool with fully documented parameters and a read-only annotation, the description is nearly complete. It would benefit from an explicit note distinguishing it from list_users or stating when to choose it, but nothing essential about how to invoke it is missing.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The endpoint string confirms that 'id' is the workspace identifier, but the description otherwise adds little semantic value beyond the parameter descriptions already present.

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

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

The description clearly states the verb 'List' and the resource 'members of a workspace', and it adds useful detail that the result includes users and their roles. It is unambiguous, though it does not explicitly differentiate itself from sibling list tools like list_users or list_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?

There is no guidance on when to use this tool versus the many sibling list tools. The endpoint reference implies the workspace scope, but no conditions, exclusions, or alternatives are mentioned, leaving selection entirely to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the organization scope and the GET endpoint, but it does not mention pagination behavior or output shape; this is acceptable 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?

The description is two short sentences with the core action front-loaded. The 'Portkey: GET /workspaces' reference is compact and useful for API identification without adding 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 operation with fully documented pagination parameters and a readOnly annotation, the description is sufficient. It identifies the resource scope, the endpoint, and the operation clearly; no output schema exists, so return-value explanation is not required.

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 clear descriptions with defaults in the schema. The tool description does not add additional parameter meaning, 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 states a specific verb ('List') and resource ('workspaces in the organization'), and the endpoint reference 'GET /workspaces' confirms the operation. It clearly distinguishes from the sibling 'portkey_get_workspace' by indicating plural collection-level listing.

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

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

The description gives clear context for what the tool does but provides no explicit guidance on when to choose it over alternatives like 'portkey_get_workspace' or how pagination should be used. Usage 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.