portkey-admin-mcp

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

Annotations indicate a mutation tool (readOnlyHint=false). Description adds precondition that user must exist in org, but does not disclose potential error cases like duplicate membership or permission requirements. Good but could be more thorough.

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

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

Two concise sentences: purpose and usage guidance. No redundant information, well-structured.

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

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

Given moderate complexity and presence of output schema, description covers key preconditions and usage steps. Could mention error handling for duplicate members, but overall sufficient.

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

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

Schema covers all parameters with descriptions. Description adds value by clarifying user_id must be UUID (not email) and referencing list_all_users, which goes beyond schema 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?

The description clearly states 'Add an existing org user to a workspace with a role,' specifying verb, resource, and constraints. It distinguishes from sibling tools like invite_user and list_all_users by referencing 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 explicitly provides prerequisites: requires UUID user_id, use list_all_users to find it, and invite_user if not in org. This gives clear when-to-use and 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?

Annotations only say readOnlyHint=false and destructiveHint=false, so the description carries the behavioral burden and delivers: it discloses soft-delete behavior ('stops treating it as active but does not permanently remove its history') and auth requirements ('Returns 403 on non-Enterprise Portkey plans'). This is exactly the kind of context the annotations do not provide. 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 content is dense and front-loaded, but 'Enterprise-gated' is repeated verbatim at the start and end — a redundant sentence that fails the 'every sentence earns its place' test. Minor trimming would make this concise rather than merely short.

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 tool with an output schema and annotations, the description is complete: it states the action, the prerequisite, the post-effect on the record, and access restrictions. Return values are covered by the output schema, so nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100% — the id parameter already has a description ('Deployment UUID to archive'). The tool description reinforces that id is a deployment UUID and implicitly sources it from get_deployment, adding marginal context beyond the schema, which matches the baseline-3 expectation for high coverage.

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

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

The description uses a specific verb-resource pair — 'Archive a registered Gateway deployment by UUID' — and clearly distinguishes archival from the delete_* siblings by disclosing soft-delete semantics. Naming get_deployment as the prerequisite further anchors what this tool is for within the large sibling set.

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

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

It gives explicit usage guidance: 'Use get_deployment first to confirm the target,' which tells the agent the correct precondition. The soft-delete explanation also implies when not to use it (when permanent removal is required), though no alternative tool is explicitly named as a contrasting option.

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

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

Beyond the destructiveHint annotation, the description discloses key behaviors: the export is 'permanently stops', takes effect 'immediately', and 'does not roll back already-processed rows'. It also states the 403 response on non-Enterprise plans, which is valuable context not in annotations.

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

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

The description is three sentences, front-loaded with the purpose. Each sentence adds distinct value: what it does, behavioral consequences/retry, and access limitations. No fluff.

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

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

Given the destructive nature, the description covers the essential context: what it cancels, permanence, no rollback, how to retry, and access restrictions. With an output schema present, return values need not be explained. This is complete for a cancellation 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?

The schema already provides 100% coverage with a description for export_id ('The unique ID of the log export to cancel'). The tool description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description opens with a specific verb+resource: 'Cancel a pending or running log export job.' It also distinguishes from siblings by explicitly naming start_log_export and delete_integration, making the tool's unique role clear.

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

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

The description states when to use this tool versus alternatives: 'unlike start_log_export which queues one or delete_integration which removes the source.' It also provides the retry workflow (create_log_export and start_log_export again) and enterprise access expectations, offering clear 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 only cover readOnly/openWorld/idempotent/destructive, so the description carries the safety burden and does it well: it discloses that the secret is returned ONCE, that it will be visible in MCP transcripts/LLM context, that the key grants access immediately, and that scope/defaults/limits apply at use. This is exactly the non-obvious behavioral 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 purpose, then surfaces the security warning prominently, then the conditional requirements. Five sentences, each carrying weight; the warning sentence is long but justified given the stakes.

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 18-parameter mutation with an output schema (so return values need no explanation), the description covers purpose, type semantics, secret handling, and prerequisites. Minor gap: no mention of rotation policy behavior or idempotency impact of repeated calls, but overall sufficient.

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

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

Schema coverage is 100% across 18 parameters, so the schema already documents each field, including the conditional workspace_id/user_id requirements. The description restates the workspace_id/user_id conditions but adds no syntax or format meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ("Create a Portkey API key for auth") and contrasts org vs workspace key scope, so the core action is unambiguous. It does not, however, distinguish itself from adjacent siblings like create_virtual_key, rotate_api_key, or create_secret_reference, which an agent must pick between.

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 selection context ("Org keys grant broader access; workspace keys are scoped") and states concrete prerequisites (workspace_id for workspace keys, user_id for user keys), which routes the caller on type/sub_type. It stops short of naming alternatives or when NOT to use this tool.

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

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

With annotations covering the safety profile (readOnly=false, destructive=false, openWorld=true), the description adds genuinely useful behavior: it returns the collection id and slug and explicitly states it 'does not move any prompts' — a real side-effect clarification. It stops short of covering idempotency or permission requirements.

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, purpose front-loaded, then usage, then the parent_id tip and return/side-effect note. Every sentence carries information an agent needs.

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

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

An output schema exists, so return values do not need explaining, yet the description still flags the id/slug return and the absence of prompt movement. Combined with full schema coverage and annotations, nothing material is missing 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 all three parameters are already documented. The description's note on parent_collection_id and workspace nesting largely restates the schema, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ('Create a new prompt collection') plus its domain purpose ('organizing prompts by app'), which separates it cleanly from siblings like create_prompt, update_collection, and list_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?

Gives concrete when-to-use guidance ('Use this when you need a new namespace before create_prompt') and a nesting condition. It does not name an explicit alternative tool or a when-not-to-use case, so it falls just 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?

Discloses important behavioral traits beyond annotations: 'At least one setting is required, new configs become active immediately once referenced by a key or prompt, and the call returns the new id and version_id.' This adds activation semantics and return value details, giving the agent clear 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?

Two sentences, front-loaded with purpose, and every clause earns its place. The structure is efficient with no redundancy or filler.

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

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

Given the 8-parameter schema with full descriptions and an output schema (so return values are already documented), the description covers all necessary contextual aspects: what it does, when to use it, key behavioral rules, and activation implications. 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 coverage is 100%, so baseline is 3. The description adds a non-obvious constraint ('At least one setting is required') not enforced by the schema (which only requires name), and mentions return fields (id, version_id), providing extra semantic context beyond the schema.

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

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

The description clearly states the tool's purpose: 'Create a config that defines routing, cache, retry, and targets for requests.' It uses a specific verb (create) and resource (config), and distinguishes itself from siblings by referencing update_config and list_config_versions as alternatives.

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

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

Explicitly provides usage guidance: 'use update_config to modify an existing one and list_config_versions for history.' This tells the agent when to use create_config versus related tools, and also implies it is for new configs only.

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

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

Annotations indicate write operation (readOnlyHint false) and non-destructive (destructiveHint false). The description adds behavioral context: 'takes effect immediately' and 'returns the created feedback IDs and status', which go beyond basic annotations. No contradictions.

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

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

The description is a single, front-loaded sentence that communicates the core action, return value, and alternative. No wasted 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?

Given the moderate complexity (4 parameters, one nested object) and presence of an output schema, the description covers purpose, usage, and behavioral impact. It could mention that weight/metadata are optional, but schema already does so. Almost 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% (all parameters have descriptions). The description does not add new semantic meaning beyond the schema; it only reinforces the trace_id link already documented. 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 verb ('create feedback'), resource ('for a trace or request'), and the linking mechanism ('by trace_id'). It explicitly distinguishes itself from the sibling tool 'update_feedback' by mentioning its use case.

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

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

The description provides explicit guidance: 'use update_feedback when correcting an existing record', which is a clear when-to-use vs when-not-to-use instruction. No other usage guidelines needed.

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 it as non-read-only, non-idempotent, open-world, and not destructive, so safety profile is largely covered. The description adds one useful behavioral fact — that the new version becomes the policy anchor for downstream use — but says nothing about permissions, scope anchoring side effects, or what happens to prior versions.

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 carrying a distinct point (what it creates, per-target requirements, downstream anchoring). Front-loaded and efficient; no wasted 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?

Given an output schema exists, return values need not be described. The description covers the two target modes, ordering semantics, and the versioning consequence, which is enough to call the tool correctly. Minor gap: no mention of required workspace/org scoping 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%, so the schema already documents all six parameters including nested checks and actions. The description adds conditional logic (checks/actions required for llm; MCP-tool can defer mapping), which slightly enriches parameter meaning but largely restates schema 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 and resource (create a guardrail) and distinguishes two flavors (LLM vs MCP-tool). It does not name sibling tools like update_guardrail or create_mcp_server, but the LLM/MCP distinction is itself differentiation within the resource.

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 a soft ordering hint: MCP-tool guardrails can be created first and mapped to servers afterward, while LLM guardrails require checks and actions. That implies when each target applies but does not explicitly say when to use create_guardrail vs update_guardrail or how it relates to the other guardrail-mapping 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 cover the safety profile (not read-only, not idempotent, not destructive), and the description adds meaningful context beyond them: key is write-only, secret_mappings resolve the key or config fields at runtime, and the call returns the new id and slug. It doesn't mention failure modes, permission requirements, or rate limits, but the added disclosure is substantive.

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?

Dense but well front-loaded, leading with the core action and role before describing parameters and follow-ups. Every sentence carries information, though the paragraph is heavy enough that a reader must work to separate creation semantics from workflow advice.

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 20-parameter creation tool with an output schema, the description covers the essential semantics plus post-creation steps and return values, so an agent has enough to invoke it correctly. Minor gaps around provider-specific field combinations (e.g., which fields are required per ai_provider_id) leave a little room.

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 genuine semantics: what ai_provider_id selects, which fields are provider-specific (Azure/Bedrock/Vertex/custom hosts), the write-only nature of key, and the discount/markup effect of pricing_adjustments. This goes beyond restating schema text.

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

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

States a specific verb and resource ('Create an AI-provider integration') and clarifies its role as the source for workspace providers, which distinguishes it from sibling create_provider and create_mcp_integration. An agent can identify the artifact being created 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?

Provides clear downstream workflow guidance ('Use update_integration_models and update_integration_workspaces after creation') and notes that tags feed list_integrations filtering. It lacks an explicit when-not or a direct contrast against create_provider/create_mcp_integration, 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?

Discloses a key behavioral trait—that creation does not start processing—and the expected follow-up workflow. Also notes the 403 error on non-Enterprise plans. While annotations indicate readOnlyHint=false, the description adds meaningful context about the asynchronous workflow and access restriction.

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 with a distinct purpose: action, workflow steps, and access caveat. Information is front-loaded and no redundant wording appears.

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 moderately complex tool with 10 parameters and an output schema, the description covers the critical workflow (create→start→retrieve) and enterprise restriction. Return values are already documented by the output schema, so no additional explanation is needed.

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

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

The input schema provides 100% coverage with detailed descriptions for all 10 parameters, including enums for requested_fields. The description only adds generic 'filters and requested fields', so it does not need to elaborate further. 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 'Create a log export definition with filters and requested fields' with a specific verb and resource. It further distinguishes the tool from siblings by explicitly noting that it 'only sets up the export and does not start processing', preventing confusion with start_log_export or download_log_export.

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

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

Provides explicit workflow guidance: 'call start_log_export next, then use get_log_export or download_log_export'. Also mentions Enterprise-gating and 403 behavior, which helps decide when to use this tool versus alternatives.

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

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

Annotations already cover the safety profile (readOnly=false, destructive=false, non-idempotent, open-world). The description adds real behavioral context beyond them: secret_mappings resolve protected values at runtime without persisting them in the call, the workspace_id requirement for admin keys, and the return payload (integration id and slug). This is genuinely additive.

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 purpose is front-loaded in the first sentence, followed by tightly packed auth and follow-up guidance. It is dense and readable with little waste, though the middle clauses run together slightly.

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

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

With an output schema present and annotations covering safety, the description need not explain return format, yet it still notes the id/slug return and the post-creation workflow. It is essentially complete for a 10-parameter creation tool, missing only explicit sibling routing.

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 goes further by explaining that custom_headers is delivered via configurations.custom_headers and that secret_mappings target configuration fields resolved at runtime. It clarifies the relationship between parameters the schema documents only in isolation.

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 ('Create a Portkey integration') and scopes it to an external MCP server URL, which separates it from the generic create_integration sibling. It does not explicitly name or contrast against the closest siblings (create_integration, update_mcp_integration), so it stops short of full differentiation.

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

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

It gives clear contextual usage: how to supply headers auth (custom_headers vs secret_mappings), that org admin keys normally need workspace_id, and that create_mcp_server plus capability/access configuration follow. It lacks explicit 'when not to use this' or named-alternative routing.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds that it registers the server and returns id/slug, but does not elaborate on potential side effects or additional behavior beyond creation. With minimal annotation context, the description provides some added value but not extensive behavioral detail.

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

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

The description is concise, consisting of two focused sentences. The first sentence states the core purpose, and the second provides contextual workflow advice. While efficient, the second sentence could be slightly more compact, but no unnecessary information is present.

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

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

Given the presence of an output schema (stated in context), the description appropriately omits detailed return value documentation. It mentions the returned id and slug. The description also advises on a necessary prerequisite step. For a creation tool with good parameter documentation, this is sufficiently complete.

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

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

The input schema has 100% description coverage for all 4 parameters. The description mentions the required parameters (name, mcp_integration_id) and notes slug and description are optional, but does not add new constraints or semantics beyond the schema. 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 creates an MCP server under an existing integration. It specifies the resource ('MCP server') and action ('Create'), and distinguishes from sibling tools by mentioning the prerequisite of using list_mcp_integrations.

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

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

The description provides explicit guidance: use list_mcp_integrations first to find the parent integration, then use this tool to create the server, and later use capabilities or access tools for configuration. This clearly indicates when to use this tool versus alternatives.

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

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

With annotations already declaring readOnlyHint=false and idempotentHint=false, the description adds useful behavior: it creates a new version immediately and returns prompt id, slug, and version id. It does not contradict the annotations. It could add a bit more about side effects or validation behavior, but the key mutation semantics are covered.

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

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

Four compact sentences, each earning its place: purpose, usage context, behavior, and parameter guidance. No filler or repetition of schema content.

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

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

For a tool with 16 parameters, nested objects, and an output schema, this description provides the critical orientation: what it creates, when to use it instead of migrate_prompt, how to handle message formats, and what it returns. It doesn't exhaustively explain every field, but the schema already does that. Minor missing context like dry_run behavior is covered by the schema, so the description is sufficiently complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful clarification beyond the schema by explaining the relationship between plain text, structured messages, and the JSON-encoded string format, specifically preferring messages for multi-message chat prompts. This helps an agent choose between the two overlapping parameter options.

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 ('Create a new prompt template and initial version') and clearly distinguishes it from migrate_prompt and update_prompt. It also names the resource and the immediate effect, so an agent can identify what this tool does 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?

Explicitly says to use this for first-time setup and points to migrate_prompt for idempotent CI/CD flows. It also gives guidance on choosing between messages and string for multi-message prompts, which is practical invocation guidance beyond the schema.

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 it is not read-only (write operation), not destructive, and open world. The description adds that it returns the new label id and does not assign to any versions. This provides useful behavioral context beyond annotations, but could mention if there are any side effects on existing labels or other entities.

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

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

The description is two sentences, front-loaded with the purpose, and every word adds value. No redundant or vague 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?

Given an output schema exists, the description does not need to detail return structure but mentions the id. It covers scope requirement, lack of assignment, and optional color. For a creation tool with 5 parameters, this is sufficiently complete.

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

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

Schema covers all parameters with descriptions. The description adds that either organisation_id or workspace_id is required (though schema marks only name as required), which is a critical constraint. It also clarifies that color_code is optional and defaults to a default color. This adds meaning beyond the schema.

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

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

The description clearly states 'Create a prompt label' and gives concrete examples like 'production, staging, or experiment'. It distinguishes the tool from siblings by noting that it does not assign the label to any versions yet, which sets it apart from assignment or update actions.

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 specifies that either organisation_id or workspace_id is required to set scope, providing clear guidance on parameter usage. It also notes that the label is not assigned to versions, implying a subsequent step. However, it does not explicitly state when to use this tool versus alternatives like update_prompt_label.

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 provide basic hints (readOnlyHint=false), and the description adds behavioral context: returns specific IDs (partial id, slug, version id) and notes the version remains inactive until published. This goes beyond annotations without contradiction.

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

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

Two sentences, no wasted words. The verb and resource are front-loaded, and the key return values and state are succinctly covered.

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 existence of an output schema, the description appropriately focuses on key return fields and version state. It omits details like workspace_id requirements for org-level keys, but overall it is sufficiently complete for a creation 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?

Input schema has 100% coverage with descriptions for all 4 parameters. The description does not add extra meaning beyond the schema, so baseline of 3 is appropriate.

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

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

The description clearly states the action ('Create') and the resource ('reusable prompt partial'), and explains its purpose for shared snippets/macros. It distinguishes itself from siblings like 'create_prompt' by emphasizing reusability and the inactive status until publication.

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

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

The description provides a clear use case ('for shared snippets or macros') and mentions that the version stays inactive until published, which guides when to use. However, it does not explicitly state when not to use this tool or mention alternatives like 'publish_partial' for activation.

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 write operation (readOnlyHint=false) that is not destructive (destructiveHint=false). The description adds behavioral detail that the provider inherits the integration key but enforces limits and expiration independently per workspace, providing nuance beyond annotations. It could mention error conditions like duplicate 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?

Two sentences efficiently cover purpose, behavioral context, and return value with no wasted words. Very concise.

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

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

Given 12 parameters and the presence of an output schema, the description adequately covers creation and the return of id and slug. It could mention the prerequisite of an existing integration, but overall it is complete for a creation tool with annotations.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds context about how integration_id and workspace_id interact (inherits key but independent limits), which adds value beyond individual parameter descriptions. No redundancy.

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 'Create' and the resource 'workspace provider backed by an org integration', distinguishing it from sibling tools like create_integration and update_provider. It also mentions the return value.

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 provider tied to an integration is needed, but does not explicitly state when to use or not use this tool versus siblings like create_integration or create_virtual_key. No exclusions or alternatives 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 establish a write, non-idempotent, non-destructive profile, and the description agrees with that. It adds value beyond the annotations by disclosing a validation constraint (non-empty conditions/grouping will otherwise fail) and the target-dependent key scoping behavior. It does not disclose duplicate-policy behavior, but idempotentHint=false already signals that risk.

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 totaling roughly 35 words: the core purpose comes first, and the two critical constraints follow immediately. No filler, no repetition of schema content, and every clause carries 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 9-parameter create tool with an output schema present, the two constraints most likely to cause a failed call — non-empty conditions/grouping and target-appropriate keys — are both captured. The only minor gap is that the description never guides when to choose 'requests' versus 'tokens', though the schema's type and value descriptions cover their meaning. Nothing essential for a correct first call 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 is 3. The description earns a 4 by adding the cross-parameter insight that the choice of target (llm vs mcp_tools) dictates which keys are valid in conditions and group_by — a relationship no individual schema field description states.

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 names a specific verb ('Create') and resource ('request or token rate-limit policy'), which cleanly differentiates this from siblings update_rate_limit, delete_rate_limit, get_rate_limit, and the similarly-named create_usage_limit. The requests-vs-tokens distinction is front-loaded so an agent immediately understands it creates counter-based rate-limit policies, not spend caps.

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 operational context — conditions and grouping must be non-empty, and target llm versus target mcp_tools determines which keys apply — but it never names an alternative or a when-not condition. An agent must infer when to prefer create_rate_limit over create_usage_limit or update_rate_limit from the create_ verb and resource name alone.

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 mutating operation (readOnlyHint=false), but the description adds side-effect context: it provisions access for current and future members, can pre-create the group via scim_group_name, and may return 403 on non-Enterprise plans. This goes well beyond the structured fields and provides essential behavioral 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?

Four sentences, each adding distinctive information: core purpose, parameter constraint/pre-creation, discovery tool references, side-effect/enterprise-403 warning. No redundant filler or repetition of schema details.

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

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

For a complex SCIM mapping operation with an output schema present, the description covers purpose, prerequisites, parameter selection rule, side effects, and error condition. It leaves return-value documentation to the output schema, which is acceptable. No significant 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 schema already documents all four parameters with descriptions covering the one-of constraint. The description reinforces the exactly-one rule and adds the pre-creation behavior for scim_group_name, which is not in the schema. Given 100% schema coverage, this extra nuance elevates the score above 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 opens with a specific verb+object+effect: 'Map one identity-provider SCIM group to a Portkey workspace role so current and future group members receive access automatically.' It clearly distinguishes from sibling `add_workspace_member` by stating it grants access via group rather than individually.

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

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

Explicitly names prerequisite discovery tools (list_scim_groups, list_workspaces) and compares to the alternative add_workspace_member, stating when this tool is appropriate ('distinct from... grants one user directly'). Also notes Enterprise-gated plans.

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

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

Goes beyond the annotations by disclosing a real behavioral trait: authentication credentials are transmitted to Portkey and exposed in the MCP transcript, and the response returns only the UUID and slug, never the resolved secret value. This credential-exposure warning is exactly the kind of context annotations (readOnlyHint=false, destructiveHint=false) cannot convey.

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

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

Three sentences, tightly front-loaded with the action, then the security caveat, then the return contract. No filler.

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

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

An output schema exists and annotations cover the mutation profile, so the description's job is to add what those miss — it does so with the credential-transcript warning and the 'never returns the resolved secret' guarantee. Minor gap: no idempotency/duplicate-slug behavior for a create operation the annotations mark non-idempotent.

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 auth_config union is thoroughly documented in-schema, so the baseline is 3. The description adds only the high-level manager list, not syntax or format detail beyond what the schema already provides.

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

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

States a specific verb and resource ('Create a reference to a secret') and enumerates the supported external managers, which cleanly separates it from get_secret_reference, update_secret_reference and delete_secret_reference in the sibling list.

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

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

Gives an actionable usage preference ('use short-lived or workload identity modes when possible'), which steers the agent toward the safer auth shapes. It does not, however, name the sibling alternatives (update/delete/get_secret_reference) or state when not to use this tool.

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

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

Annotations already indicate this is a write operation and non-destructive; the description adds value by clarifying that an omitted periodic_reset results in a cumulative lifetime limit. It also communicates the validation constraint that conditions and grouping must be non-empty, which is useful beyond the schema alone.

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, front-loaded sentences capture the purpose, key constraints, and reset behavior with no filler. Every clause adds distinct information that an agent needs for correct tool selection and 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?

Given the rich input schema, output schema, and annotations, the description covers the essential decision-making context. It could be slightly more complete by explicitly contrasting with create_rate_limit, but the current wording is sufficient for an agent to understand the tool's role.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantics by explaining that periodic_reset can be weekly, monthly, or null for a lifetime cumulative limit, and by associating 'cumulative cost or token' with the type parameter.

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

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

The description clearly states a specific action ('Create'), resource ('cumulative cost or token usage-limit policy'), and key constraints ('with non-empty conditions and grouping'). This distinguishes it from related siblings like create_rate_limit and update_usage_limit by emphasizing cumulative usage budgets.

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 implies when to use this tool: when creating a cumulative cost/token policy rather than a rate-based limit. It does not explicitly name alternatives or state exclusions, but the 'cumulative' qualifier and reset semantics provide clear contextual 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 non-readonly, non-destructive, non-idempotent, openWorld. The description adds real value beyond that: the raw key is encrypted and returned only at creation time, limits apply immediately, and it returns the new slug. It omits the key/secret_mappings interaction, which the schema covers.

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, front-loaded with the core action and the critical caveat about saving the returned key. Minimal waste, though the final 'returns the new slug' clause is slightly redundant with the earlier mention.

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

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

An output schema exists, so return details need not be explained. For a 14-parameter tool the description covers the essential behavioral and lifecycle facts; the main gaps are the alternative-tool routing and the key-vs-secret_mappings dependency.

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 14 parameters, including the key/secret_mappings conditional. The description adds essentially no parameter-level 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?

States a specific verb and resource: 'Store a provider API key as a virtual key.' It's clear what the tool does. It doesn't explicitly differentiate from the sibling create_api_key or update_virtual_key, so it falls short of 5.

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 implied usage ('use it in prompts/configs') but never states when to choose this over create_api_key or update_virtual_key, nor any prerequisites. Context is implied rather than explicit.

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

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

Annotations already declare it is a non-read-only, non-idempotent, open-world create, so the safety profile is covered. The description adds real value by disclosing the slug auto-generation fallback and stating the returned fields (id, name, slug), which helps the agent chain calls. It does not mention permission requirements or whether the operation can fail on duplicates.

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 front-loaded sentences with no filler; the core action leads and the fallback behavior follows. Slight redundancy in restating return values that the output schema already covers.

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 tool with 8 parameters including nested rate_limits and usage_limits objects, the description is thin on defaults and constraints, but the full-coverage schema and an output schema carry that load. Annotations plus the stated return fields make it sufficient to call correctly.

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

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

Schema description coverage is 100%, including the slug auto-generation note, so the schema already documents parameters thoroughly. The description's restatement of the slug fallback and return fields adds only marginal meaning beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ("Create a workspace") plus the functional intent ("isolate resources, API keys, and team members"), which tells an agent what the object is for. It does not explicitly contrast with siblings like update_workspace or create_scim_workspace_mapping, but the create verb 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?

There is no when-to-use guidance, no note about required permissions or account context, and no mention of an alternative tool for related operations. The only conditional (slug omitted) is a behavioral detail, not usage guidance.

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

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

Adds behavioral details beyond annotations: states it cannot be undone, revokes immediately, can break sessions, and returns success after revocation. Annotations only provide destructiveHint=true.

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

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

Two sentences, all information relevant and front-loaded. No unnecessary 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?

Covers the effect and response, but does not mention prerequisites like permissions. For a simple delete, it is still fairly complete given annotations and output schema exist.

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 100% of the single parameter with description. Description adds no extra param details beyond mentioning UUID, so baseline 3 applies.

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

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

Description states specific action 'Delete an API key by UUID', clearly distinguishing from siblings like create_api_key and update_api_key.

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 mentions permanence, immediate revocation, and potential impact on active sessions. Could be improved by contrasting with alternatives, but the destructive context 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 indicate destructiveHint=true. The description adds context about irreversibility and the effect on prompts (lose grouping), going beyond annotations. It does not contradict any annotation.

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

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

The description is two sentences: first states the purpose, second adds behavioral context. Every sentence adds value, and it is front-loaded. No wasted 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?

The description covers the core action and its effects. It is complete for a simple delete operation with one parameter. Could mention the output schema, but not necessary.

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% coverage with a description for collection_id. The tool description does not add additional 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 clearly states 'Delete a prompt collection by ID', specifying the verb and resource. It distinguishes itself from siblings like delete_prompt by focusing on collections and their effect on prompt grouping.

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 guidance on when to use (delete collection) and warns about consequences ('cannot be undone'). It suggests reassigning prompts first if organization matters, but does not explicitly list alternatives or when not to use.

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

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

Beyond the destructiveHint annotation, the description adds key details: permanent deletion, removal of all versions, and breaking anything pointing to the slug. No contradictions.

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

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

A single sentence with two concise clauses, front-loaded with the action. Every word adds value; no unnecessary text.

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

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

For a simple delete tool with an output schema (exists elsewhere), the description covers the action, permanence, and a crucial precaution. It is fully adequate for an agent to use without ambiguity.

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

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

The schema provides 100% coverage for the single parameter 'slug' with description 'Configuration slug to delete'. The description does not add additional parameter details, meeting 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?

Description clearly states 'Delete a config by slug.' It explicitly names the resource and action, and the sibling tools (create_config, update_config, get_config, list_configs) make it 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?

The description warns of permanence and breaks dependencies, and suggests checking list_config_versions first. It provides clear when-to-use/not-use context, but lacks explicit mention of alternatives like update_config for deprecation.

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 goes beyond the annotations (destructiveHint=true) by detailing the irreversible nature and the cascading effect on configs. This adds valuable behavioral context about consequences, complementing the annotation.

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

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

The description is two concise sentences. The first sentence states the purpose, and the second provides a critical warning. No unnecessary words, earning its place.

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

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

Given the simple nature of a delete operation with one required parameter and an existing output schema, the description covers all necessary context: what it does, how to identify the guardrail, and the irreversible consequences. Complete 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?

The only parameter 'guardrail_id' is already well-described in the schema as 'The guardrail UUID or slug to delete'. The description does not add additional meaning beyond what the schema provides, meeting the baseline for 100% coverage.

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

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

The description clearly states the verb 'Delete' and the resource 'guardrail', specifying identification by 'id or slug'. It distinguishes itself from sibling tools like 'create_guardrail' or 'update_guardrail'.

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

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

The description provides explicit guidance: it warns that the action is irreversible and removes checks from dependent configs, advising to review those first. While it doesn't explicitly list when not to use, the warning implies careful consideration. It offers clear context for usage.

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

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

Annotations already set destructiveHint=true and readOnlyHint=false. The description adds value by specifying irreversibility and cascading effects on virtual keys, providers, and workspace access.

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

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

The description is two sentences long, front-loaded with the primary action, and every sentence adds critical information without redundancy.

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

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

For a single-parameter delete operation, the description covers purpose, consequences, and parameter. It is nearly complete, though the output schema is not described.

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 100% schema coverage, the description adds no extra meaning beyond the schema's explanation of the 'slug' parameter. 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 'Delete an integration by slug,' providing a specific verb and resource. It distinguishes this tool from siblings like delete_api_key or delete_provider, which target different entities.

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

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

The description explains that deletion is irreversible and breaks dependent entities, giving clear context for when to use the tool. However, it does not explicitly mention when not to use it or suggest 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?

Beyond annotations (destructiveHint=true), the description explains that deletion only applies to custom entries and that success is returned after removal. This adds behavioral context not fully captured 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?

Two sentences, no wasted words, front-loaded with action and key constraint. Highly concise and well-structured.

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

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

For a simple delete tool with full schema coverage and an output schema, the description covers purpose, usage, behavioral traits, and return behavior completely. Annotations and schema handle the rest.

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

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

Schema coverage is 100%, and the description does not add additional meaning to the parameters beyond their names and definitions in the schema. Baseline score applies.

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

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

The description clearly states the action ('Delete a custom model from an integration') and distinguishes between custom and built-in models, implying that built-ins should be handled differently. This differentiates it from sibling tools like 'update_integration_models'.

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

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

The description explicitly states when to use (custom models) and when not to (built-in models should be disabled instead), providing clear usage guidelines. It does not name the alternative tool but implies 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?

Adds behavioral context beyond annotations: irreversible, removes access immediately, cascades to servers. Annotations only mark destructiveHint=true; the description fills in the details.

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

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

Two sentences, no wasted words. Action and implications front-loaded, making it easy to quickly understand.

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 destructive delete operation, the description covers irreversibility, immediate impact, cascade, and a usage precaution. Output schema exists, so return values need not be described. Comprehensive.

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

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

The input schema already provides a description for the single parameter 'id' (the integration ID or slug). The tool description does not add further parameter information, so baseline 3 applies.

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

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

The description clearly states the action 'Delete an MCP integration and all servers beneath it', using a specific verb and resource. It distinguishes from sibling delete operations like delete_mcp_server by noting the cascade effect.

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

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

Explicitly states when to use: after confirming nothing depends on the integration, and warns of irreversibility and immediate access removal. No alternative tools are named, but the caution is sufficient for an irreversible delete.

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 destructiveHint=true, but the description adds critical behavioral context: the operation is irreversible and immediately removes connected users' access. This goes beyond the annotation's binary hint. No contradiction with annotations.

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

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

The description is three sentences long, providing all necessary information without redundancy. The first sentence states the action, and subsequent sentences add essential warnings. Every sentence earns its place.

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

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

Given there is an output schema, the description does not need to describe return values. It covers the irreversible nature, immediate user impact, and the caution about workflows. It is sufficient for the agent to use 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?

The parameter 'id' is fully described in the schema ('The MCP server ID or slug to delete'). The description does not add any additional semantic meaning beyond what the schema already provides. With 100% schema coverage, a 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 ('Delete') and the resource ('MCP server instance'), making the purpose immediately clear. Among many sibling delete tools, the tool name 'delete_mcp_server' combined with the description sufficiently differentiates it.

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 an important usage condition: 'should be used only after confirming no workflows depend on the server.' This advises the agent on when it is appropriate to invoke the tool. However, it does not explicitly mention alternatives or when not to use it.

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false. The description adds specific behavioral context: 'This cannot be undone, immediately breaks callers using the slug,' which goes beyond annotations. However, it does not detail any rate limits or permission requirements.

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

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

The description is two sentences with no unnecessary words. It front-loads the core action ('Delete a prompt...'), then adds critical caveats. 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 destructive one-parameter tool with an output schema, the description covers what is deleted, irreversibility, impact on callers, and prerequisite checks. It is complete given the tool's simplicity and the presence of annotations.

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

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

The input schema has 100% coverage for the single parameter 'prompt_id' with a clear description ('Prompt ID or slug to delete'). The tool description adds no additional 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 clearly states the action: 'Delete a prompt and all its versions by id.' It uses a specific verb ('Delete') and resource ('prompt and all its versions'), distinguishing it from sibling tools like 'delete_prompt_label' or 'delete_prompt_partial'.

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

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

The description provides explicit guidance: 'should only be used after checking list_prompt_versions or confirming you do not need an audit trail.' It warns about irreversibility and impact on callers ('immediately breaks callers using the slug'), helping decide when to use this tool versus alternatives.

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

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

The description goes beyond annotations by detailing the irreversible nature and downstream effects on versions and workflows. Annotations only flag destructiveHint=true, but the description explains what gets destroyed.

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

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

Two concise sentences: first states the action, second explains key consequences. Every word is necessary, no fluff.

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

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

The tool has one parameter and an output schema (though not shown, it exists). The description covers the essential behavioral impact, making it complete for this simple tool.

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

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

With 100% schema coverage and only one parameter, the schema already describes the parameter as 'Label ID to delete.' The description does not add additional semantics, so baseline score applies.

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

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

The description clearly states the action: 'Delete a prompt label by ID.' It uses a specific verb and resource, distinguishing it from sibling tools like update_prompt_label or create_prompt_label.

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 consequences: 'cannot be undone', 'versions carrying the label lose it', and 'any workflow resolving by that label will need a replacement.' This helps the agent decide when to use it cautiously, though it does not explicitly name 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?

Beyond annotations (destructiveHint=true), the description adds that deletion is irreversible and affects dependent prompts. This clarifies the side-effect and non-idempotent nature beyond the structured 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: first states the action, second adds the critical consequence. No unnecessary words, well front-loaded.

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

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

Given the simple one-parameter tool and existence of an output schema (per context signals), the description adequately covers the action and side effects. It is complete for the complexity level.

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?

Only one parameter with 100% schema coverage. The schema already describes it as 'Prompt partial ID or slug to delete.' The description adds no extra details beyond 'by ID,' so baseline 3.

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

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

The description clearly states the action: 'Delete a prompt partial by ID.' It specifies the resource and identifier, distinguishing it from siblings like 'update_prompt_partial' and 'create_prompt_partial.'

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

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

The description explains the consequence (permanent deletion, prompt render failures) but does not explicitly state when to use this vs. alternatives like updating or disabling. The warning about reference replacement provides practical 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 destructiveHint=true. The description goes further by specifying that deletion is irreversible and will break prompts, configs, and virtual keys, adding valuable behavioral details 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?

Two sentences, front-loaded with action, then consequences and alternative. Every word is necessary and there is 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?

With destructiveHint=true and clear description of consequences, the tool is well-specified. However, it lacks details about permissions or rate limits, which would make it fully complete. Output schema existence is implied but not detailed.

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 has 100% description coverage for both parameters (slug, workspace_id). The description does not add extra meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Delete' and the resource 'workspace provider by slug'. It also distinguishes itself from the sibling tool 'delete_integration' for the org source, eliminating 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?

Explicitly states when to use (delete a workspace provider) and when not to (use delete_integration for org source). Also warns about irreversibility and impacts on other entities, providing clear context for decision-making.

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

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

Annotations already declare destructiveHint=true, and the description adds valuable context beyond that: removal is immediate and impacts active throttling, so dependent callers should be checked. This meaningfully augments the structured metadata without contradicting it.

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

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

Two tight sentences with no filler. The core action is front-loaded, and the second sentence adds only high-value safety context. 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?

The tool has a single fully documented parameter, an output schema, and destructive annotations. The description adds the missing behavioral warning about immediate policy removal and dependent callers, making it complete for safe 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%, with the id parameter already documented as 'Rate-limit policy UUID to delete.' The description only restates 'by id' and does not add new semantic detail beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Delete a rate-limit policy by id.' This clearly separates it from sibling delete tools like delete_usage_limit, and the additional context about removing the active throttling policy reinforces what the operation does.

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

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

The description gives clear practical guidance: before deleting, inspect dependent callers and the full policy. It does not explicitly name alternatives such as get_rate_limit or update_rate_limit, but the warning about immediate removal provides sufficient decision context for when this destructive action is appropriate.

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

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

Beyond annotations (destructiveHint, idempotentHint), the description adds critical behavior: existing provisioned members remain, Enterprise-gating, and 403 error on non-Enterprise plans. This gives the agent important context to set expectations and handle errors.

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

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

The description is tightly written in three sentences, each providing unique, necessary information. It is front-loaded with the primary action, followed by consequential details, with no wasted 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?

Given the single parameter, rich annotations, and presence of an output schema, the description covers all relevant context: purpose, side effects, prerequisites, exclusions, gating, and error behavior. It is fully self-sufficient for an agent to 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%, but the description adds value by specifying that mapping_id comes from list_scim_workspace_mappings. This reinforces the parameter's origin, though it could include more details about required format or validation.

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 ('Delete') and resource ('SCIM group-to-workspace mapping'), clearly distinguishing it from sibling tools like create_scim_workspace_mapping and list_scim_workspace_mappings. It also states the key side effect (stopping future group updates), 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 explicitly instructs to 'Inspect list_scim_workspace_mappings first', providing a clear prerequisite and source for the mapping_id. It also clarifies exclusions (does not delete the identity-provider group or the Portkey workspace), helping the agent avoid misuse.

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 destructiveHint=true and idempotentHint=true; description adds detail about irreversible nature and immediate impact on dependent integrations/virtual keys, providing context 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?

Two concise sentences, front-loaded with action and permanence, then dependency warning. No wasted 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 single-parameter destructive operation with full annotations and an output schema, description comprehensively covers consequences and prerequisites.

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 100% of parameter with description 'Secret Reference UUID or slug'. Description adds no further parameter meaning beyond what schema provides.

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

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

Clearly states 'Permanently delete a Secret Reference' with specific verb and resource. Distinguishes from sibling delete tools by specifying the entity type.

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 warns to confirm dependencies before deletion and describes consequences, but does not state when to avoid using or suggest 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 indicate destructive behavior, and the description adds useful nuance: the policy stops enforcing its budget but remains available through archived-status reads. This clarifies that the operation is an archival action with retained history, going beyond the raw destructiveHint annotation.

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

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

The description is a single, compact sentence that front-loads the primary action and then explains the consequential behavior. Every word contributes meaning, with no redundant or filler content.

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

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

For a one-parameter destructive operation with an output schema and clear annotations, the description covers what the tool does, what happens to the policy, and what remains accessible afterward. Nothing necessary for correct invocation 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%, and the only parameter 'id' is already well-described as 'Usage-limit policy UUID to archive'. The tool description repeats 'by id' but does not add additional semantic detail beyond the schema, 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 uses a specific verb, 'Archive', and a specific resource, 'cumulative usage-limit policy by id', making the tool's action clear. It also distinguishes itself from related destructive tools like delete_rate_limit by clarifying that this is an archive operation, not a hard deletion.

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 implies when to use the tool: when you want to stop a usage-limit policy from enforcing its budget while retaining its historical record. It does not explicitly state when not to use it or name alternative tools, but the retention behavior provides clear context.

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

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

Beyond the annotations (destructiveHint=true), the description details the permanent nature of deletion and its consequences: removes memberships, revokes keys, ends sessions. This provides comprehensive 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?

The description is two sentences: the first delivers the core purpose and effects, the second provides an alternative. It is concise and front-loaded with essential information, with no wasted 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 delete tool with one parameter, the description covers purpose, behavioral effects, and an alternative. The output schema exists but does not require additional description. The tool is fully specified.

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 parameter 'user_id' with a description. The tool description does not add additional semantics beyond the schema. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states the verb 'delete', the resource 'user', and the method 'by id'. It differentiates from the sibling tool 'delete_user_invite' by specifying that tool is for pending invites. The scope of deletion is thoroughly explained.

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

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

The description explicitly states when to use this tool (to delete a user by ID) and provides a direct alternative for a specific case ('use delete_user_invite for pending invites instead'). This is clear 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 include destructiveHint=true, so the safety profile is already indicated. The description adds that the invite link is revoked and that existing users are unaffected, providing extra context 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?

Two concise sentences with no redundant information. Every phrase adds value, and the structure is efficient.

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 delete tool with one parameter and an existing output schema, the description covers purpose, scope, and exclusions thoroughly, leaving no ambiguity.

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 one parameter (invite_id) already documented. The description does not elaborate on parameter meaning beyond schema, but the schema itself is clear.

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 'Delete a pending invite and revoke its invite link,' specifying the action and resource. Distinguishes from 'delete_user' by noting it does not affect existing users, helping the agent differentiate among 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?

Explicitly provides when to use (delete pending invite) and when not to (does not affect existing users), and directs to 'delete_user' for full removal, offering a clear alternative.

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