portkey-admin-mcp

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive open-world mutation, so the safety profile is covered. The description adds the real operational constraint that the target must already be an org member and that membership is granted with a specific role, but doesn't say what happens on a duplicate add or what permissions the caller 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?

Two short sentences, zero waste, and the prerequisite chain is ordered correctly after the core action. Everything an agent needs is front-loaded.

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

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

Three required params are fully documented in the schema, an output schema exists, and the description covers the sequencing prerequisite that the schema cannot express. Only error/duplicate behavior and required caller permissions are missing for full completeness.

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

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

Schema coverage is 100% and the role enum is documented in the schema, including the UUID/not-an-email note. The description only adds the provenance hint (get it from list_all_users), which the schema already states, so it adds little beyond structured fields.

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 ('Add an existing org user to a workspace') plus the role assignment, which distinguishes it clearly from update_workspace_member, remove_workspace_member, and invite_user. An agent can select it without opening the schema.

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

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

Explicitly routes the agent to list_all_users to resolve user_id and names invite_user as the prerequisite when the person isn't in the org yet. Both the when-to-use and the preconditions are stated outright.

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 substantial context beyond the annotations: it explains that the record is soft-deleted, that active status is stopped but history is preserved (consistent with destructiveHint=false), and that non-Enterprise plans receive a 403. Auth gating and side-effect scope are exactly what an agent needs before invoking a mutation.

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?

Short and front-loaded, with every sentence carrying weight except the duplicated 'Enterprise-gated.' phrase, which appears both at the opening and near the end. Minor redundancy keeps it from a 5.

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 mutation with an output schema already defined, the description covers the prerequisite lookup, the gating requirement, the error condition, and the reversibility of the effect. Nothing an agent needs in order to call 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% and the single 'id' parameter is already documented as 'Deployment UUID to archive'. The description's 'by UUID' phrasing reinforces the identifier format but adds no syntax, format, or sourcing detail 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 ('Archive') and a specific resource ('a registered Gateway deployment') plus the identifier form ('by UUID'). This is clearly distinct from update_deployment, get_deployment, and register_deployment in the sibling list, which only read or modify a deployment.

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

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

Explicitly instructs the agent to call get_deployment first to confirm the target, and the soft-delete semantics distinguish this from a permanent removal path. It stops short of stating when NOT to archive (e.g., when traffic is still routed to the deployment), so it falls one step short of a full 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, but the description goes well beyond them: it states the stop is permanent, takes effect immediately, and explicitly does not roll back already-processed rows. It also discloses the Enterprise plan gate and the 403 response for non-Enterprise plans, which annotations cannot express.

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

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

Three short sentences, zero filler. The core action and scope come first, sibling disambiguation second, and the retry/eligibility caveats last – a well front-loaded structure for a destructive tool.

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

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

An output schema exists, so return values need not be explained. For a destructive, single-parameter mutation, the description covers reversibility, timing, side effects, retry path, and authorization gating – nothing an agent needs to call it safely 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?

Only one parameter (export_id) and schema description coverage is 100%, so the schema already carries the meaning. The description adds nothing about ID format or where to obtain the export_id, which is the appropriate baseline-3 outcome when the schema does the heavy lifting.

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

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

Names a specific verb (cancel) plus a resource (log export job) and narrows the target state to 'pending or running'. It also explicitly distinguishes itself from start_log_export (queues) and delete_integration (removes the source), so an agent can pick it out of a large sibling set without opening any schema.

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

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

Gives both when-to-use-by-contrast (it is not start_log_export and not delete_integration) and the exact remediation path if the cancel was a mistake: call create_log_export and start_log_export again to retry. The Enterprise gating and 403 outcome are stated as preconditions, so an agent can pre-check eligibility.

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 declare it is a non-idempotent, non-destructive write, which says little about access semantics. The description goes well beyond that by disclosing the effect-inference rule for omitted effect (deny only when both user ANY and agent ANY are present, otherwise allow requiring a specific subject), which is exactly the kind of surprising default an agent must know. It stops short of stating permission requirements or what happens on 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?

Four compact sentences, front-loaded with purpose and value, then the non-obvious default rule, then the return/next-step note. Dense but every clause carries information; "which requires a specific subject" is slightly compressed and takes a re-read.

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?

Return value is noted as a UUID (output schema exists, so no need to elaborate further), the ordering hint against get_access_policy is present, and the key semantic trap is covered. Gaps are minor: it doesn't flag the workspace_id/org-level-key requirement, though the schema does.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by explaining the omitted-effect inference rule that the schema only gestures at with "inferred." It does not otherwise add syntax detail for subjects/targets, which is fine since the schema is thorough.

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 access policy") plus the supported subject kinds and target kinds, which distinguishes it cleanly from update_access_policy and get_access_policy in the sibling set. The second sentence names the actual effect ("Changes who may access those targets") so an agent knows the blast radius without opening the schema.

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

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

Gives a concrete workflow instruction: "use get_access_policy before later updates," which routes the agent correctly against the sibling read tool. It does not explicitly contrast with update_access_policy or delete_access_policy, so when-not-to-use remains implicit.

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

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

The description adds critical behavior beyond the annotations: the key secret is returned only once, will be visible in MCP transcripts and LLM context, and must be stored securely immediately. It also warns that the key grants access immediately according to its scopes, defaults, and limits. This is exactly the kind of security-sensitive behavioral context an agent needs for a create operation.

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

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

The description is front-loaded with purpose, then gives key-type guidance and a prominent security warning. It is appropriately sized for a security-sensitive create tool, though the sentence about immediate access according to scopes/defaults/limits is slightly redundant with the earlier warning.

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, full parameter descriptions, and annotations, the description covers the most important missing context: one-time secret exposure and secure storage. It does not describe permission prerequisites for creating keys or contrast with sibling key-management tools, but it is largely complete for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all 18 parameters thoroughly. The description repeats the workspace_id and user_id requirements and the org/workspace access distinction, but it does not add meaningful semantics beyond what the schema already provides. 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 states a specific verb and resource: "Create a Portkey API key for auth." It also distinguishes org-wide vs workspace-scoped keys, so an agent can understand the tool's scope without opening the schema. The only minor gap is that it does not explicitly contrast with sibling tools like create_virtual_key, but the resource is clearly different.

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

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

The description gives useful context about key types and required IDs, but it does not explicitly say when to use this tool versus alternatives such as create_virtual_key, rotate_api_key, or create_access_policy. Usage is implied by "for auth" and the org/workspace distinction, but no exclusions or alternative routing are provided.

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 the mutation profile (readOnly=false, destructive=false, idempotent=false, openWorld=true), so the bar is lower. The description adds real value beyond them by stating 'does not move any prompts' — ruling out a side effect an agent might otherwise fear — and noting the returned id and slug.

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

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

Three sentences, front-loaded with the core action, with each subsequent sentence carrying a distinct fact (prerequisite context, nesting, return/side-effects). Minor redundancy with the schema on parent_collection_id keeps it from a 5.

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 three-parameter creation tool with full schema coverage and an output schema, the description covers purpose, prerequisite timing, nesting behavior, and side-effect scope. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so all three parameters are already documented. The description's note about parent_collection_id nesting essentially restates the schema's own wording, adding no new syntax or format detail. 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 new prompt collection') plus its scope ('organizing prompts by app'), which cleanly separates it from update_collection, list_collections, and delete_collection. An agent can identify the operation without opening the schema.

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

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

Gives an explicit trigger ('when you need a new namespace before create_prompt') and routes to the nesting case via parent_collection_id. It does not mention when to prefer update_collection for an existing collection, but the pre-creation 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 already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds genuinely new behavior: a minimum-settings constraint, that configs activate immediately once referenced by a key or prompt, and the returned id/version_id. It stops short of covering permissions or duplicate-name behavior.

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

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

A single dense sentence that front-loads purpose, then alternatives, then constraints and return value. No filler, and each clause carries distinct information.

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

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

With an output schema present and 100% param coverage, the description needs only to frame purpose and routing, which it does, plus activation semantics. Missing only minor edges such as name-uniqueness and workspace defaulting.

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 eight parameters are already documented including enums and bounds. The description only loosely groups them ('routing, cache, retry, targets') and adds the 'at least one setting is required' constraint, which is a modest value-add over the schema.

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

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

States a specific verb (Create) and resource (config) plus the domains it governs: routing, cache, retry, and targets. It explicitly names the sibling tools it is not (update_config, list_config_versions), so an agent can distinguish it without opening the schema.

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

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

Explicitly routes the agent to update_config for modification and list_config_versions for history, which is the main ambiguity for a create_* tool. It does not state hard preconditions (e.g., whether name must be unique or a workspace must exist), so it falls short of a full when/when-not treatment.

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, openWorld, non-idempotent and non-destructive. The description adds material context beyond them: the entry widens outbound egress (a security-sensitive mutation), duplicates and metadata destinations are rejected, organisation permission is required, and the entry is normalized. Return-shape detail overlaps the existing output schema, which slightly weakens the added value.

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 what is being created and its effect, followed by the precondition, the failure modes, and the output. No filler or redundancy.

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

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

For a two-parameter mutation with a rich schema, full annotation coverage and an output schema, the description supplies everything an agent still needs: the security implication, the prerequisite lookup, permission requirement, and rejection rules. Nothing material 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 domain parameter description already covers trimming/lowercasing and metadata rejection, so the description adds essentially nothing new on parameters. Duplicate rejection is a useful extra behavioral note but not a parameter-level clarification. 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 (trust/create an entry) and resource (organisation egress allowlist) plus the accepted value shapes (hostname, IP literal, wildcard) and the effect of widening outbound destinations. It is unmistakably distinct from get_/update_/delete_egress_allowlist_entry and list_egress_allowlist.

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 routes the agent to list_egress_allowlist to check existing trust first, which is the main precondition for this create. It doesn't state when not to use it (e.g. when a broader wildcard should be avoided or when an update is preferable), so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnly=false, destructive=false, and idempotent=false, so safety profile is covered. The description adds genuine context beyond them: it writes a NEW record linked by trace_id, takes effect immediately, and returns created IDs and status — useful for an agent deciding whether to retry or verify.

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

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

Front-loaded with the core action, then the write/return/immediacy details, then the alternative routing. Efficient and every clause adds information, though it is a single dense sentence that could be split for scannability.

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

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

With an output schema present, the description needn't detail return values, and annotations cover safety. It supplies the essential extras (immediate effect, trace_id linkage, update_feedback alternative), leaving little an agent needs missing for correct invocation.

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

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

Schema description coverage is 100%, so value, weight, metadata, and trace_id are fully documented in the schema. The description only reinforces that trace_id links the record; baseline 3 is appropriate when the schema carries the parameter burden.

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 feedback') and the scope ('for a trace or request'), then immediately distinguishes itself from the sibling update_feedback. An agent can tell exactly what this 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 routes the agent: 'use update_feedback when correcting an existing record,' which gives a clear when-to-use-this vs alternative rule. It doesn't state exclusions beyond that (e.g., prerequisites like valid trace_id existence), so it stops just short of a full 5.

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

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

Annotations already cover the safety profile (non-read-only, non-destructive, non-idempotent, open-world), so the description earns credit for the extra claim that the created version becomes the 'policy anchor for downstream use' – non-obvious versioning semantics an agent would otherwise miss. It still doesn't say whether the guardrail is immediately active/enforced or whether creation fails on 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?

Three short sentences, front-loaded with what is created, then the variant-specific constraints, then the downstream consequence. No filler or restatement of the tool name.

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

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

An output schema exists and annotations cover mutability, so the description needn't explain return values. Given six parameters including nested checks/actions, it covers the essential structural distinction between the two target modes, but omits scoping behavior (workspace vs organisation id) and enforcement timing.

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

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

Schema coverage is 100%, so the schema documents all six parameters and the baseline is 3. The description goes beyond the schema by stating the conditional requirement (checks and actions for LLM targets) and the default target behavior, which is real semantic value the schema only encodes indirectly.

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 ('Create an LLM or MCP-tool guardrail') and immediately splits the resource into its two variants, which an agent can act on. It does not explicitly contrast itself with create_guardrail's closest siblings (update_guardrail, list_guardrails), so it stops just 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 states a meaningful usage condition – LLM guardrails need checks and actions, while MCP-tool guardrails may be created bare and mapped to servers later – which implies the correct ordering of operations. It never says when to use this versus update_guardrail or what happens if a guardrail already exists, so the guidance is inferred 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?

With annotations already covering safety (readOnly=false, destructive=false, idempotent=false, openWorld=true), the description adds real context: key is write-only, secret_mappings resolve values at runtime, create_default_provider defaults to true, and the return value (new id and slug). It omits auth/permission requirements and duplicate-name conflict behavior.

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

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

One dense paragraph with no filler sentences; the scoping statement is front-loaded and follow-up tools are last. It is slightly run-on, packing provider fields, defaults, secrets, pricing, tags and next steps into a single block without visual grouping.

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 (so return values needn't be described), it covers the default behavior, conditional provider fields, secrets substitution and follow-up mutations. Missing only failure modes and permission/scope constraints, which an agent creating integrations would benefit from.

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

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

Schema coverage is 100% so the baseline is 3; the description earns above that by grouping the provider-specific fields (Azure/Bedrock/Vertex/custom hosts) semantically, explaining ai_provider_id's role as backend selector, and noting that tags feed list_integrations filtering and that secret_mappings can substitute for key.

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?

Opens with a specific verb+resource plus a role statement ('becomes the source for workspace providers'), which separates it from create_provider/list_integrations. The distinction from create_provider is implied through 'source for workspace providers' rather than named explicitly, keeping it just below top marks.

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 explicit post-creation sequencing ('Use update_integration_models and update_integration_workspaces after creation'), but never states when to choose this over create_provider or list_integrations, nor any prerequisites or exclusions. Usage is implied rather than routed.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context not in annotations: that creation is a setup-only step with no processing triggered, and that non-Enterprise plans receive a 403. It stops short of covering duplicate-definition behavior or limits, so a 4 rather than 5.

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

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

Three short sentences, front-loaded with what the tool does, then the workflow, then the entitlement caveat. Every sentence adds information an agent needs and nothing is repeated from structured fields.

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

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

The output schema covers return values, so the description needn't explain them. It supplies exactly what the structured data cannot: the setup-only semantics, the required follow-up call, and the Enterprise entitlement gate. Nothing needed 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% with per-field descriptions, so the schema already carries the parameter burden. The description only restates that filters and requested fields exist, adding no syntax or constraint detail beyond the schema — the 3 baseline applies.

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

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

States a specific verb and resource ('Create a log export definition with filters and requested fields') and immediately delimits scope: it only sets up the export and does not start processing. That distinguishes it cleanly from siblings start_log_export, get_log_export, and 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?

Explicitly names the next step ('call start_log_export next') and the follow-up alternatives ('get_log_export or download_log_export'), plus the entitlement precondition (Enterprise-gated, 403 otherwise). There is no ambiguity about when to use this versus its siblings.

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

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

Beyond the annotations (non-read-only, non-destructive, non-idempotent, open-world), it discloses two things an agent cannot infer: secret_mappings resolve protected values at runtime rather than being stored in the call, and the tool returns the integration id and slug for chaining. It does not discuss failure modes or what happens on duplicate names/slugs, but the annotations already carry most of the safety profile.

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 dense sentences, front-loaded with the core action and then auth, workspace, and post-creation sequencing. Every sentence carries information, though the auth sentence is packed with three distinct ideas and could have been split for scanability.

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 10-parameter, nested-object, open-world creation tool with full schema coverage and an output schema, the description supplies exactly the missing connective tissue: the two auth patterns, the org-admin workspace caveat, and the mandatory follow-up calls. Return values are already covered by the output schema, so nothing material is absent.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes slightly beyond by clarifying the routing relationship between custom_headers and configurations.custom_headers and by framing secret_mappings as runtime-resolved targets against configurations.<field>. It still leaves value_format and secret_key selection entirely to the schema, so it is an increment rather than a full semantic layer.

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

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

The first sentence gives a specific verb and resource — creating a Portkey integration that points at an external MCP server URL — which cleanly separates it from the sibling create_integration (LLM provider) and from create_mcp_server, which the description explicitly names as the follow-up step. An agent can pick this tool out of the large sibling list 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?

It gives concrete conditional guidance: use custom_headers or a Secret Reference mapping for headers auth, and organisation admin keys 'normally need workspace_id'. It also sequences the workflow (create, then create_mcp_server and configure capabilities/access). It stops short of stating when to prefer update_mcp_integration over this tool or any exclusions, so it is clear context rather than a full when/when-not rule set.

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

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

Annotations already declare this is a non-read-only, open-world, non-idempotent, non-destructive operation, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it requires a pre-existing parent integration and must be followed by capability/access configuration to be useful. Return-value detail is partly redundant with the output schema.

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

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

Two sentences, front-loaded with the action and scope, then the prerequisite and follow-up. Zero filler and nothing redundant.

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

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

With a full output schema, complete parameter descriptions, and annotations covering safety, the description supplies the remaining pieces an agent needs: the dependency on an existing integration and the natural next tools. Minor gaps around auth/permission requirements keep it from a 5.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description does not add format, constraints, or slug-generation behavior beyond what the schema states, so baseline 3 applies.

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

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

States a specific verb and resource ("Create an MCP server") and immediately narrows scope with "under an existing integration," which distinguishes it from the sibling create_mcp_integration. An agent can tell the two apart without inspecting either schema.

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

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

Gives a concrete prerequisite workflow ("use list_mcp_integrations first to find the parent integration") and follow-up guidance (capabilities or access tools to configure it). It does not explicitly cover when to prefer create_mcp_integration instead, but the parent-integration framing implies the boundary.

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

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

Annotations already declare readOnly=false, idempotent=false, destructive=false, so the safety profile is partly covered; the description adds real value by disclosing that a version is created immediately as a side effect and what identifiers are returned ('prompt id, slug, and version id'). It does not state what happens on name/slug collision, which is the main residual unknown for a non-idempotent create.

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

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

Three short sentences with no filler: what it does, when to use it versus the alternative, then input format and return shape. Purpose and the sibling routing are front-loaded before the mechanical 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 16-parameter creation tool with nested objects, the description covers purpose, the sibling alternative, input-format choice, and return identifiers, and an output schema exists so return values need no elaboration. A short note on the dry_run preview path or on model-selection exclusivity would have made it fully self-sufficient, but nothing critical is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description goes beyond it by establishing a preference order the schema does not ('pass messages (preferred) or a JSON-encoded array as string') and by naming the plain-text path. The other 14 parameters, including the mutually exclusive model/ai_model_id/finetune_id trio, are left entirely to the schema.

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

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

States a specific verb and resource ('Create a new prompt template and initial version') and immediately names the sibling it is not (migrate_prompt). An agent can distinguish it from update_prompt, publish_prompt, and migrate_prompt without opening any schema.

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

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

Explicit routing: 'Use this for first-time setup; use migrate_prompt for idempotent CI/CD flows.' It names the alternative and the exact condition that selects it, which is the strongest form of guidance available.

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

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

Annotations already declare this is a non-readonly, non-destructive, non-idempotent mutation. The description adds genuinely new behavioral facts: a scope prerequisite (org or workspace) and the crucial disclosure that no versions are tagged yet, which an agent could otherwise assume.

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 dense sentence that front-loads the purpose, then the scope requirement, then the post-condition. No filler and nothing important buried.

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

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

An output schema exists so return shape needn't be described, and the description still flags the new label id. Combined with the scope rule and the unassigned-state caveat, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds a constraint the schema omits: neither ID is marked required, yet one must be supplied to set scope. That is meaningful semantics beyond the structured fields.

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 prompt label') and immediately scopes it with concrete examples (production, staging, experiment), which distinguishes it from create_prompt, update_prompt_label, and the list/get/delete label siblings.

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

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

Gives clear operating context — one of organisation_id/workspace_id must set the scope, and the label is created unassigned to versions. It doesn't explicitly route the agent to a sibling (e.g. update_prompt_label for attaching), so it stops short of full when/when-not guidance.

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

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

Annotations already declare the mutation/non-idempotent/non-destructive profile, and the description adds genuinely non-obvious behavior: it returns the partial id, slug and version id, and the created version is inactive until published. That lifecycle detail is the key thing an agent could get wrong. It omits any note on workspace scoping or permissions.

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

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

A single front-loaded sentence covering purpose, usage, return values and lifecycle. It is dense with semicolon-joined clauses, but every clause carries information; nothing is padding.

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

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

For a 4-parameter create tool with an output schema and full annotation coverage, the description covers what it creates, why, and the inactive-version lifecycle. Remaining gaps (auth/workspace scoping) are partly covered by the schema field description for workspace_id.

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

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

Schema description coverage is 100%, so all four parameters (name, string, workspace_id, version_description) are already documented in the schema. The description adds no parameter-level detail beyond implying that the content is a template referencing partials. 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 reusable prompt partial') and immediately clarifies the mechanism of use ('inclusion with {{> partial_name}}') and the intent ('shared snippets or macros'), which distinguishes it from the sibling create_prompt for full prompts. An agent can identify it without opening the schema.

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

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

'Use this for shared snippets or macros' gives an explicit selection criterion versus full prompts, and the note that the new version stays inactive until published implicitly routes to publish_partial. No explicit exclusions or prerequisites (e.g. workspace scoping for org keys) are stated in the description.

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 explaining that the provider inherits the integration key while limits and expiration are enforced independently per workspace – a real behavioral trait an agent wouldn't infer from the schema. Annotations already carry the safety profile (non-idempotent, non-destructive, open-world), so remaining gaps like permission requirements are minor.

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, then the key semantic distinction, then the return value. 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?

An output schema exists, so the return description is a bonus rather than a necessity. The description adequately frames a 12-param creation tool's core semantics, though it doesn't touch the org-admin workspace_id nuance or rate/usage limit interplay.

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 parameters are already well documented and the baseline is 3. The description's note about inheriting the integration key and independent limit enforcement adds indirect meaning but no direct per-parameter clarification.

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 workspace provider') and adds a qualifying relationship ('backed by an org integration') that separates it from create_integration. It does not explicitly name sibling alternatives, so it falls short of a 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?

The 'backed by an org integration' framing implies the key precondition (an existing integration_id is needed), but the description never says when to use create_provider versus update_provider or how it relates to workspace scoping. Usage is only implied.

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

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

Annotations already disclose that this is a non-destructive, non-idempotent, open-world write operation. The description adds target-specific key semantics but largely repeats the schema's non-empty constraints and does not explain permissions, duplicate handling, or side effects.

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 efficient sentences, front-loaded with the core action and immediately followed by the most important configuration rules. No filler.

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

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

With an output schema and full schema descriptions present, return values and most parameter details are already covered. The description supplies the key creation semantics and target-specific key mapping, though it could say more about scoping via workspace_id or organisation_id.

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 useful meaning by explicitly binding target values to key families: llm maps to model/provider keys, while mcp_tools maps to MCP server/tool keys, which helps configure group_by and conditions correctly.

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

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

The description states a specific verb and resource: creating a request or token rate-limit policy. It distinguishes the two counter types clearly. However, it does not differentiate this tool from sibling tools such as create_usage_limit or update_rate_limit.

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 creation semantics and validation constraints but gives no explicit guidance on when to use this tool versus alternatives like create_usage_limit or update_rate_limit. An agent must infer the choice from the tool 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?

The description goes beyond annotations by disclosing that this changes access provisioning, that a group name can pre-create a Portkey SCIM group, and that non-Enterprise plans return 403. It does not contradict the annotations, though it could add more on duplicate-mapping behavior or idempotency.

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

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

The description is front-loaded around the core mapping action, then follows with parameter selection, discovery helpers, sibling distinction, and Enterprise gating. Every sentence adds useful routing or behavioral information without unnecessary restatement.

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 schema, existing output schema, and annotations, the description supplies the routing, selection rules, side effect, and plan gating an agent needs. Return values need not be explained because an output schema exists.

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, but the description adds meaningful semantics by emphasizing exactly-one selection between scim_group_id and scim_group_name and explaining the pre-creation effect of using a name. The workspace_id and role meanings remain mostly schema-driven.

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 the specific action clearly: map one identity-provider SCIM group to a Portkey workspace role so members receive access automatically. It names the sibling alternative add_workspace_member and distinguishes itself from that tool, so an agent can select correctly without opening another 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 explicit selection rules: use exactly one of scim_group_id or scim_group_name, use list_scim_groups to discover groups, and use list_workspaces to obtain the workspace ID. It also states when this differs from add_workspace_member and adds the Enterprise-plan precondition.

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 information the annotations cannot express: that auth credentials are transmitted to Portkey and become visible in the MCP transcript, which is a material security consequence for a non-read-only, open-world call. It also commits to a return contract ('returns the new UUID and slug, never the resolved external secret'), removing any assumption that the secret value might be echoed back.

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: purpose first, security/credential-handling warning second, return contract third. No restatement of the name, no filler, and the most important caveat is placed before any detail.

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

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

For an 11-parameter tool with a deeply unioned auth_config, the description covers purpose, credential exposure, and output shape, while an output schema and annotations carry the return and safety details. It omits org-scoping and workspace-permission context (organisation_id, allowed_workspaces, allow_all_workspaces), but those are documented in the schema.

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

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

Schema description coverage is 100%, including per-variant guidance on the auth_config union and the manager_type enum, so the baseline is 3. The description itself adds no parameter-level detail beyond naming the three secret managers, which the enum already encodes.

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 scopes it to three named external managers. The create verb plus the 'reference, not the secret' framing makes it separable from get_secret_reference, update_secret_reference, and list_secret_references, though no sibling is named explicitly.

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

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

The description never states when to use this tool versus update_secret_reference or get_secret_reference; that must be inferred from the name. It does contain directional guidance ('use short-lived or workload identity modes when possible'), but that is about which auth mode to pick, not about when to invoke the tool.

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

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

Annotations already declare this is a non-destructive, non-idempotent mutation. The description adds useful semantics about cumulative lifetime limits when periodic_reset is omitted, but it doesn't mention side effects, permission requirements, or what happens on duplicate creation beyond the non-idempotent hint.

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, both front-loaded and free of repetition. The purpose comes first, followed by the reset semantics, with no wasted wording.

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

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

Given a rich schema with 100% coverage, annotations, and an output schema, the description is complete enough for correct invocation. Minor gaps like not mentioning workspace/organisation scoping or alert_threshold are acceptable because the schema covers them.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters in detail. The description only clarifies the meaning of omitting periodic_reset (lifetime limit), which adds minor value beyond the schema's 'Optional reset schedule' wording.

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 and resource ('Create a cumulative cost or token usage-limit policy'), making the operation clear. It implicitly distinguishes itself from rate-limit siblings by emphasizing 'cumulative' and periodic resets, though it doesn't name the alternative tool explicitly.

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

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

It states that conditions and grouping must be non-empty and explains reset options, which implies when the tool is applicable. However, it never says when to choose this over create_rate_limit or update_usage_limit, leaving the agent to infer the distinction.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), yet the description still adds real behavioral facts: the raw key is encrypted and retrievable only at creation time, and optional usage/rate limits take effect immediately. It stops short of covering permissions, error conditions, or what happens on 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?

Three tight sentences with the core action front-loaded and no filler. Minor deduction because "the raw key is encrypted and only returned at creation time" reads ambiguously next to "save the returned slug" — a reader could momentarily think the raw key itself comes back.

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 14-parameter create tool whose schema is fully documented and which has an output schema, the description covers what an agent needs to call it correctly: what is created, that the secret is write-only, and that the slug must be retained. The unmentioned alternative paths (secret_mappings vs. raw key) are documented in the schema itself.

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

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

Schema description coverage is 100% across all 14 parameters, so the schema already documents provider, expires_at, Azure fields, secret_mappings, and deployment_configurations. The description only gestures at the limit parameters ("optional usage and rate limits") without adding syntax or defaults, so the baseline of 3 applies.

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

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

States a specific verb and resource: "Store a provider API key as a virtual key." That is clear enough to distinguish it from list/get/update/delete_virtual_key, but it never contrasts with the adjacent create_api_key or create_secret_reference tools, which a caller could plausibly confuse it with.

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 post-call guidance ("save the returned slug and use it in prompts/configs") which implies the intended workflow, but it never says when to choose this over create_api_key or when to use secret_mappings instead of passing a raw key. Usage is only implied.

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

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

Annotations declare openWorldHint=true, idempotentHint=false, destructiveHint=false, covering the safety profile. The description adds genuinely useful behavioral context beyond the annotations: slug auto-generation from name when omitted, and that the response includes id, name and slug.

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, front-loaded with the core action and purpose, followed by the slug/return detail. 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 mutation with nested rate/usage-limit objects and an output schema, the description plus rich schema/annotations gives an agent enough to call it correctly. Slightly incomplete on guidance for the optional rate_limits/usage_limits setup, but those are well documented in the schema.

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

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

Schema description coverage is 100%, so all 8 parameters are documented there; the baseline is 3. The description adds a bit of value on the slug auto-generation rule but says nothing about the complex rate_limits/usage_limits or is_default semantics 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 ('create') and resource ('workspace') plus the isolation purpose (resources, API keys, team members), which clearly distinguishes it from get_workspace/update_workspace/delete_workspace. It doesn't explicitly name a sibling to prefer, but 'create' is inherently 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?

Usage is implied by the verb – use this to make a new workspace – but there is no explicit when-to-use/when-not guidance or reference to alternatives like update_workspace or add_workspace_member for adding members after creation.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description adds real value on top: the concrete side effect (allow/deny rule removed, access permissions changed), irreversibility ('cannot be undone by this tool'), the acknowledgement return, and the HTTP 404 behavior for missing policies.

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

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

Three short sentences, front-loaded with the action and effect, followed by the irreversibility warning, the prerequisite, and the error contract. No sentence is filler.

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

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

With an output schema present and rich annotations, the description covers what an agent still needs: motivation for the prerequisite read, the destructive effect's scope, irreversibility, and the 404 failure mode. Nothing material is missing for a single-parameter destructive tool.

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

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

Schema coverage is 100% and the schema already states the id is an access policy UUID sourced from list_access_policies or create_access_policy. The description only restates 'by UUID', adding no format or sourcing detail 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 and resource ('Delete an access policy by UUID') and describes the concrete effect ('removing its allow or deny rule and changing access permissions'). This clearly separates it from siblings like get_access_policy, update_access_policy, and list_access_policies.

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

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

Explicitly directs the agent to inspect get_access_policy first, which is a concrete pre-condition for safe invocation. It does not, however, name the alternative for non-destructive modification (update_access_policy) or state when deletion is the wrong choice.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds real value beyond them: irreversibility, immediate access revocation, and the fact that live sessions using the key can break. It stops short of stating what a repeat delete returns (given idempotentHint=false) or what permissions are required.

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

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

Three short sentences, front-loaded with the action, then consequences. The closing "Returns success after revocation" is largely redundant given an output schema exists, so it is not perfectly waste-free.

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 tool with an output schema and full annotation coverage, the description supplies the operational consequences an agent needs before calling. Only authorization prerequisites and post-delete state are left implicit.

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

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

Schema coverage is 100% — the single `id` parameter already carries a description, a UUID format, and a strict pattern. The description only restates "by UUID," adding no format, sourcing, or lookup guidance beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Delete an API key") plus the identifier form (UUID), which is unambiguous. It does not distinguish itself from the sibling rotate_api_key, which is the natural alternative for invalidating a key without permanent removal.

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

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

The description gives no when-to-use or when-not-to-use guidance and never names rotate_api_key or update_api_key as alternatives for the common case of key compromise. The consequence sentences imply caution but do not route the agent to a safer sibling.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, yet the description adds genuinely new information: the deletion is irreversible and the contained prompts survive in the workspace but lose their collection grouping. That side-effect disclosure goes well beyond what the structured fields 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?

Two sentences, no filler, with the destructive nature front-loaded immediately after the action. The recovery advice follows naturally in the same sentence, so every clause earns its place.

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

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

An output schema exists, so return values need not be explained, and the tool has one parameter. The description covers the action, its irreversibility, its effect on child entities, and the mitigation step; nothing an agent needs in order to call it safely is missing.

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

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

The single parameter has 100% schema description coverage and is self-explanatory ('Collection ID to delete'). The description only echoes this with 'by ID' and adds no naming, sourcing, or lookup guidance beyond the schema, so the baseline applies.

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

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

States a specific verb and resource ('Delete a prompt collection by ID'), which unambiguously separates it from update_collection and get_collection in the sibling list. It does not explicitly name or contrast a neighboring tool, so it falls just short of the top mark.

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 precondition ('reassign them first if organization matters'), which implies when to prepare before calling. However, it never states when not to use this tool or which sibling to use instead (e.g., update_collection to just regroup prompts), leaving the alternative choice to inference.

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

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

Annotations already flag destructiveHint=true, but the description goes further and explains exactly what is destroyed: permanence, removal of all versions, and downstream breakage of anything referencing the slug. That downstream-impact detail is not derivable from the schema or annotations and is the most decision-relevant fact for an agent.

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

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

One front-loaded sentence pair: what it does, then the consequences and the prerequisite check. No boilerplate, no restatement of the name.

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

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

For a one-parameter destructive tool with full annotation coverage and an output schema, the description supplies the missing pieces: irreversibility, cascade scope, and a verification step. Nothing an agent needs before invoking it is absent.

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

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

Single parameter with 100% schema description coverage, so the schema already explains 'slug'. The phrase 'by slug' in the description adds nothing beyond it; baseline 3 applies when the schema carries parameter meaning.

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

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

States a specific verb (delete) and resource (config) plus the identifying key (slug). It is unambiguously distinct from siblings like update_config, get_config, and list_configs, which operate on the same resource without destroying 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?

Gives a concrete pre-flight step, 'check list_config_versions first', and names the sibling to use for it, which is genuinely actionable. It stops short of stating the when-not case (e.g., 'use update_config to modify instead of deleting'), so it is clear context rather than full 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?

Goes well beyond the destructiveHint/idempotentHint annotations by naming the blast radius (integrations that use the destination break), stating irreversibility ('Deletion cannot be undone by this tool'), the required organisation permission, and the response contract (acknowledgement or HTTP 404). These are exactly the operational facts an agent needs before committing to a destructive call.

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 tightly packed sentences ordered by importance: what it does and its risk, the prerequisite inspection, then irreversibility/permissions/response. No filler or restatement of the tool name.

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

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

For a one-parameter destructive tool with an output schema and full annotation coverage, this covers the remaining gaps: prerequisite, permission requirement, blast radius, reversibility, and the error case. Nothing material is missing for correct invocation.

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

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

The single `id` parameter has 100% schema description coverage, including its UUID format and the two sibling tools that produce valid values, so the schema already does the work. The description adds nothing about the parameter, which is the correct baseline-3 outcome when coverage is complete.

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 (Remove) and resource (organisation egress allowlist entry), immediately followed by the consequence of the action (revoking trust in the outbound destination). This is unambiguously distinct from the create/get/update/list egress siblings in the toolset.

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 routes the agent to run get_egress_allowlist_entry before deleting, which is a concrete pre-call prerequisite, and warns that integrations using the destination may break. It lacks an explicit statement of when not to delete or which sibling handles the safer alternative (update vs delete), 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?

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety bar is low, yet the description adds substantive detail the annotation cannot convey: the deletion is irreversible and silently removes the check from any referencing configs. That cascade effect is the key behavioral fact 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?

Two sentences, zero filler, with the irreversible/cascade warning placed immediately after the action so it reads before the agent commits.

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 safety profile, so the description only needs to carry the cascade and irreversibility facts — which it does. Minor gap: no mention of what happens on an unknown id or whether the response confirms dependent configs affected.

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 single parameter already documents 'UUID or slug'. The description restates the same information without adding format, validation, or resolution-order details, 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 (delete) and resource (guardrail) plus the accepted identifier forms (id or slug). It is unmistakably a removal tool, though it never names its sibling update_guardrail as the non-destructive alternative.

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

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

Gives a concrete precondition — review dependent configs before calling — which is real usage context. It stops short of naming alternatives (e.g., update_guardrail to disable instead of delete) or saying when deletion is the wrong choice.

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 substantial context beyond the destructiveHint annotation: the action is irreversible, stops the org-level connection, and breaks dependent virtual keys, providers, and workspace access. This gives the agent concrete consequences needed before invoking a destructive mutation.

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 tightly written sentences, front-loaded with the action and followed by the critical irreversible-impact warning. No wasted wording.

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

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

For a destructive mutation with annotations and an output schema, the description covers the important behavioral context: irreversibility and the specific dependent resources affected. Nothing essential is missing for an agent to decide whether to call it.

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

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

The single slug parameter has 100% schema description coverage, so the schema already explains it. The description mentions deletion by slug but adds no further syntax, format, or lookup guidance beyond the schema.

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

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

States a specific verb and resource: delete an integration by slug. It is clear what the tool does, though it does not explicitly distinguish itself from related sibling tools such as delete_mcp_integration or delete_integration_model.

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

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

The description makes clear this is an irreversible deletion and implies caution by listing downstream breakage. However, it does not explicitly say when to use this versus alternatives like update_integration, 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 declare destructiveHint=true and idempotentHint=false, so the safety profile is covered; the description adds the non-obvious constraint that only custom models are eligible and that success is returned once removal completes. It stops short of stating that the call fails on built-in models or repeated deletes.

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

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

Three short sentences, front-loaded with the action and the primary exclusion, with no redundant restatement of the tool name.

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

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

An output schema exists and annotations carry the destructive/non-idempotent profile, so the description only needs the domain constraint, which it supplies. Missing only the failure mode (built-in model rejection) and irreversibility wording.

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

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

Schema description coverage is 100% and both parameters (slug, model_slug) are documented there, so the description adds no parameter-level meaning beyond naming the integration and the model. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Delete a custom model from an integration') and immediately bounds the scope to custom entries, which distinguishes it from the sibling update_integration_models path used to disable built-ins. An agent can identify the target object and the exact effect 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 gives a when-not-to-use rule: built-in models should be disabled instead because deletion only applies to custom entries. It does not name the concrete sibling tool that performs the disable, so the agent must infer the alternative, but the decision boundary itself is unambiguous.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds information annotations cannot convey: the delete is a cascade that removes all child MCP servers, and connected access is cut immediately rather than lingering. It does not cover permission requirements or whether confirmation/re-auth is enforced server-side.

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

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

Two sentences with no filler; the destructive scope is front-loaded before the safety caveat, which is the right order for an agent skimming before a destructive call.

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 tool with an output schema, the description covers what is destroyed, irreversibility, and the precondition for calling it. Only prerequisite/permission context is absent, which is a minor gap.

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

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

With a single parameter and 100% schema description coverage ('The MCP integration ID or slug to delete'), the schema carries the full burden. The description mentions no parameter detail, 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 and resource ('Delete an MCP integration') and adds the cascade scope ('and all servers beneath it'), which distinguishes it from the sibling delete_mcp_server and delete_integration tools without opening a schema.

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

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

Gives an explicit precondition ('should only be used after confirming nothing depends on the integration'), which is meaningful guidance for a destructive call. It does not name a safer alternative (e.g., delete_mcp_server for a single server, or update_mcp_integration to detach), so it stops short of full routing guidance.

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

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

Annotations already flag destructiveHint=true, so the description's extra value is disclosing consequences: the operation "cannot be undone" and immediately cuts off dependent users and workflows. That is meaningful behavioral context beyond the annotation. It stops short of covering permissions or what happens to related resources.

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

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

Two sentences with zero padding. The destructive nature is front-loaded, and the warning about disconnecting users follows immediately.

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 tool with annotations and an output schema, the description covers the essential risk context and irreversibility. It could say more about side effects on related resources (e.g., capabilities, access entries), but nothing critical is missing.

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

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

The single parameter is fully documented in the schema (100% coverage: "The MCP server ID or slug to delete"). The description adds nothing about the identifier's format or how to obtain it, so the base level of 3 applies when the schema carries the full burden.

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

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

The description states a clear verb and resource: "Delete an MCP server." That is unambiguous and matches the tool name. However, it doesn't distinguish this from close siblings like disconnect_mcp_server_connection or delete_mcp_integration, so the agent has to infer the boundary.

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?

"Use with caution, as it will immediately disconnect any users or workflows depending on it" gives a risk-based precondition, which implies when not to use it. But it never names an alternative (e.g., disconnect vs. delete) or states explicit when-to-use criteria, so the guidance is implied rather than directive.

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 readOnlyHint=false, but the description adds valuable operational context beyond them: the action is irreversible, it deletes all versions, it breaks slug-based callers immediately, and it has audit-trail implications. This is exactly the kind of behavioral disclosure an agent needs for a destructive operation.

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

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

The description is compact and front-loaded: it states the core action first, then the irreversible consequence, then the recommended precaution. Every clause carries useful information.

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

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

Given the rich annotations, complete parameter schema, and presence of an output schema, the description covers what the agent most needs to know before invoking a destructive delete. It addresses irreversibility, scope, caller impact, and audit-trail considerations without unnecessary detail.

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

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

Schema coverage is 100% and the single prompt_id parameter is already documented as accepting an ID or slug. The description reinforces ID-based deletion but does not add syntax or handling details 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 states a specific verb and resource ('Delete a prompt') plus an important scope detail ('all its versions by id'). This clearly distinguishes it from prompt-related siblings like update_prompt, get_prompt, or list_prompt_versions.

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 conditions for use: only after checking list_prompt_versions or confirming no audit trail is needed. It also explains a key consequence that should influence tool selection: callers using the slug will break immediately.

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, idempotentHint=false, and openWorldHint=true, so the description's job is narrower. It still adds real value by spelling out the downstream effects: irreversibility, versions losing the label, and workflows resolving by that label requiring a replacement. It stops short of mentioning auth requirements or rate limits.

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

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

Two short sentences; the operation is front-loaded and the destructive consequences follow immediately. 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?

With rich annotations, an output schema, and a single fully documented parameter, the description covers the one thing structured fields can't express: the ripple effects of deletion. Missing only explicit guidance on the alternative path for label reassignment.

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 (label_id) with 100% schema description coverage. The description's 'by ID' adds nothing the schema doesn't already say, 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 and resource ('Delete a prompt label') and the selector ('by ID'), which cleanly distinguishes it from the sibling CRUD operations create_prompt_label, update_prompt_label, get_prompt_label, and list_prompt_labels.

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

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

The description makes the consequences explicit enough that an agent can judge whether deletion is appropriate, and it warns about the workflow-replacement precondition. It does not, however, explicitly name alternatives (e.g., update_prompt_label to reassign) or state when not to 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 declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral information beyond that: the operation is irreversible and it produces a cascade failure in any prompt that references the partial via {{> name}}. It does not mention permission requirements or what happens to historical versions, but the cascade consequence is exactly the kind of context annotations cannot carry.

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

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

Two sentences, zero filler, with the irreversibility stated immediately after the action and the rendering consequence front-loaded as the second sentence. Every clause earns its place.

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

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

An output schema exists and annotations cover the safety profile, so the description only needs to explain the action and its side effects, which it does well. The remaining gap is that it never clarifies the ID-vs-slug input or whether deleting a published partial behaves differently, which matters for a destructive tool.

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

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

Schema description coverage is 100%, so the single parameter is already documented as 'Prompt partial ID or slug to delete'. The description restates 'by ID' and in fact narrows the schema's broader 'ID or slug' contract, adding no new meaning. Baseline 3 applies when the schema does the work, and here it does.

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

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

Specific verb+resource: deletes a prompt partial identified by ID. This is clearly distinguishable from delete_prompt, delete_prompt_label, and delete_workspace in the sibling list because the resource noun is precise. It stops short of stating how it differs from other prompt-partial operations (e.g. that it removes all versions), so it is clear but not maximally differentiated.

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

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

Usage context is implied rather than stated: the warning that referencing prompts will break 'until you replace the reference' hints that update_prompt_partial or reference edits should precede or follow deletion, but no alternative or precondition is named explicitly. There is no statement of when deletion is inappropriate (e.g. a published/versioned partial) or which sibling to use instead.

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, idempotentHint=false and openWorldHint=true, and the description usefully adds blast radius — prompts, configs and virtual keys referencing the provider will break — plus the post-removal success response. However, it does not address permission prerequisites (e.g. the workspace_id/org-admin-key path) or whether a failed delete leaves partial state, which are the remaining behavioral unknowns for a destructive call.

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 zero filler: identification and scope first, then the warning and the alternative routing, then the response note. Every clause carries decision-relevant information.

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

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

For a 2-parameter destructive tool with a full-schema description, complete annotations and an output schema, nothing an agent needs before invoking is missing — the danger, the sibling alternative and the return signal are all present.

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

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

Schema description coverage is 100%, so both slug and workspace_id (including the org-admin-key condition) are already documented. The description only restates that deletion is keyed by slug and adds no format, casing or lookup guidance 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 (Delete) and resource (workspace provider) plus the identifier used to address it (slug), and explicitly scopes it to workspace-level rather than org-level providers. That scope sentence distinguishes it cleanly from delete_integration and from the create/get/update/list provider siblings.

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

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

Names the alternative tool explicitly — "use delete_integration for the org source instead" — with the condition that selects it (org-level source vs workspace provider). It also flags the irreversible consequence, which is the main decision input before calling.

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, idempotentHint=false, and openWorldHint=true, so the safety bar is lower. The description still adds real context beyond them: deletion takes effect 'immediately' on the active throttling policy, implying no soft-delete/undo and immediate impact on live traffic. It does not mention required permissions or whether rollback is possible.

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

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

Two short sentences, front-loaded with the action and scope, followed by the one caution that actually changes agent behavior. No boilerplate or repetition of name/title.

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