upAPI

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

Annotations already declare this is a non-destructive, non-idempotent, closed-world mutation, so the safety profile is covered. The description adds only that the invitation must be addressed to the caller's email; it says nothing about side effects (membership creation), failure modes for expired or already-used invites, or that a second call will not succeed.

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

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

One sentence with no filler, and the key scoping constraint (your email) is front-loaded. 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?

A one-parameter tool with no output schema needs little, but the description omits what accepting actually does (e.g., joins a workspace/plan) and the error conditions an agent might need to handle. Minimum viable rather than complete.

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

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

Schema coverage is 100% for the single invitationId parameter, so the schema carries the documentation burden. The description adds no format, source, 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 (accept) and resource (invitation), which clearly separates it from list_invites, revoke_invite and invite_member. It stops short of explicitly naming those siblings, so sibling differentiation is implicit rather than spelled out.

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?

"addressed to your email" implies the caller must be the invitee, which is a useful scoping hint. There is no explicit when-to-use vs. alternatives or when-not (e.g., expired/revoked invites, or use revoke_invite to decline).

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=true and destructiveHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral fact — that removal does not delete the operation but returns it to the default product — which annotations alone would not convey. It omits permissions, side effects on existing product membership, and how `kind` affects routing.

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

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

A single front-loaded sentence with no filler; the primary action comes first and the secondary mode follows. It is efficient, though it is arguably too terse for a tool with a mode toggle and a discriminator enum.

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 five parameters, one enum discriminator, and no output schema, the description covers the core operation but leaves the toggle semantics and the hosted/api distinction to the schema. An agent could call it correctly by reading the schema, but the description alone is thin for a mutation that reassigns resources.

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 five parameters, and the baseline of 3 applies. The description hints at the add/remove duality but never names the `remove` flag, the `kind` enum values, or why `organizationId` is restricted to an approved workspace.

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 operation to a product, or move it back to the default product. An agent can grasp the effect without opening the schema. It does not, however, distinguish itself from siblings such as update_product or the list_products family, so it stops 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 two modes (add vs. move back to default) are implied, but the description never says which parameter selects the second mode — the agent must infer that `remove=true` does it. There is no explicit when-not guidance and no mention of prerequisites such as organizationId or productId validity.

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

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

The annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so safety is covered. The description adds only the returned content set, with no note on permissions, scoping to the caller's organization, or whether quota figures are live versus cached.

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 economical sentence with no filler. However, it is a bare noun phrase rather than a front-loaded action statement, which slightly weakens orientation.

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?

Since there is no output schema, the description does the useful work of naming the returned fields. But it omits scope (which organization's billing is reported when organizationId is absent) and any sibling differentiation, leaving meaningful gaps for a billing 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 single organizationId parameter is already documented as an approved workspace id. The description adds nothing about the parameter or the default behavior when it is omitted (presumably the caller's own org), so baseline 3 applies.

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

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

The description lists the resource contents (plan, renewal date, trial, quota used/remaining), which makes the domain clear, but it uses no verb and never says it retrieves/reports status. It also does not distinguish itself from overlapping siblings such as get_usage, get_account_summary, or list_plans.

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

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

There is no guidance on when to call this versus get_usage (quota) or get_account_summary, and no mention of when the optional organizationId should be supplied. The agent must infer usage entirely from the name and field list.

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, openWorldHint=true, and non-idempotent, so the safety profile is covered. The description adds genuinely new behavior: per-call quota cost that varies by operation, and the failure mode (a tool error carrying upAPI's error code rather than a broken session). It does not restate or contradict the mutation/idempotency hints explicitly, which would have made it a 5.

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

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

Three tight sentences with no filler, front-loading the action, then the prerequisite, then cost and error behavior in order of decision relevance.

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 generic dispatch tool with a nested free-form `input` object and no output schema, the description covers discovery, cost, and failure semantics well. The remaining gap is what a successful call returns (raw operation payload? envelope?), which matters even without an output schema.

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

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

Schema description coverage is 100%, so the schema already explains that `slug` must match what `search_ops` returned and that `input` mirrors the operation's listed parameters. The description repeats that relationship without adding format, validation, or edge-case detail beyond it, 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 ("Run one upAPI operation by slug") and distinguishes itself from the sibling `search_ops`, which is the discovery counterpart. An agent can tell 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?

Gives an explicit prerequisite and sequencing rule: discover slugs and their parameters with `search_ops` first, then call this. The alternative tool and the condition for using it are named directly rather than implied.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent mutation, so the safety profile is covered. The description adds the conditional-currentPassword rule, but says nothing about whether existing sessions/tokens are invalidated, whether the change requires an authenticated session, or what happens on failure.

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 filler, with the core action front-loaded and the conditional requirement immediately after. Nothing is wasted.

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, fully schema-documented tool with clear annotations and no output schema, this covers what an agent needs to invoke it. Only side effects (session invalidation, auth requirements) are absent, which is a minor gap rather than a blocking one.

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 both parameters are already described in the schema ('At least 8 characters', 'Required if a password is already set'). The description's currentPassword clause essentially restates the schema text, adding no new format or constraint 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 ('Set a new password'), which is unambiguous and clearly distinct from the account/profile/API-key siblings. It doesn't need to name an alternative because none of the listed siblings overlap with password setting.

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 second sentence conveys a conditional prerequisite (accounts with an existing password must supply currentPassword), which is useful context. However, there is no guidance on when to use this versus update_profile or delete_account, and no mention of authentication state or what happens to existing sessions.

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 state readOnlyHint=false, destructiveHint=false, idempotentHint=true and closed-world, so the safety profile is covered structurally. The description adds nothing beyond that: not what gets mutated, whether the flag is per-user or per-org, nor any permission requirement — which matters a lot for a tool taking an organizationId.

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

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

One short sentence is not waste, but it is under-specification rather than conciseness: it uses its only clause on a metaphor instead of stating the state change or scope. Nothing is front-loaded because there is nothing substantive to front-load.

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 tool with annotations but no output schema and an optional organization parameter, the description should at least say what is completed, for whom, and what is returned. As written, an agent cannot confidently call this on the right target or predict the effect.

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 organizationId is documented in the schema ("Approved workspace id only."), so baseline 3 applies. The description does not clarify why the parameter is optional (0 required) or what happens when it is omitted — a meaningful gap the schema leaves open.

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?

"Mark the welcome checklist done" essentially restates the tool name (complete_onboarding) in metaphorical terms: it never says what the checklist is, what state change occurs, or what record is touched. No sibling is named or implicitly excluded, so the agent can't distinguish this from other workspace-mutating tools in the list.

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

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

There is no guidance on when to call this versus alternatives, no preconditions (e.g., that onboarding must be in progress, or that the caller needs to be a member/admin of the organization), and no note about what happens on repeat invocation. Usage is left entirely to inference.

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

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

Annotations already declare this is a non-readonly, non-destructive, non-idempotent write. The description adds crucial context beyond that: the secret is returned only once and permissions must be user-supplied, both of which affect how an agent should call it. It stops short of describing what else the response contains.

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, though the safety instruction leads ahead of the core purpose, which is slightly less front-loaded for an agent scanning for what the tool does. Every sentence carries actionable content.

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

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

For a three-parameter mutation with no output schema, the description covers the key risk points: one-time secret return and user-driven permission selection. It does not mention anything about the organizationId constraint beyond what the schema already states, but that is adequately covered there.

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 67% with terse field labels ('Tier', 'Key name'). The description compensates by explaining the omitted-tiers default ('Omit tiers for all') and by framing tiers as permissions that must be chosen by the user, adding real meaning the schema lacks.

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 ('Creates a key') and adds a distinguishing behavioral fact ('returns the secret once'). This cleanly separates it from sibling tools like list_api_keys, revoke_api_key, and rotate_api_key.

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

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

It gives an explicit usage rule ('Ask the user which permissions the key needs; never choose for them') and a default-behavior rule ('Omit tiers for all'). It doesn't explicitly name alternative tools, but the sibling names (revoke, rotate, list) make the routing 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 readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the agent knows this is a non-destructive, non-idempotent write. The description adds nothing beyond that: no mention of permissions, name-collision behavior, what happens on repeat calls, or side effects on operations.

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

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

One short sentence with no waste, but it is under-specified rather than efficient. The single sentence fails to front-load the creation action or any usage context.

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 tool that creates a resource with no output schema, the description should clarify what is returned or what a product contains relative to operations. It omits this entirely, so an agent cannot judge the effect of calling it.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no meaning to name, description, or organizationId (including the 'Approved workspace id only' constraint), leaving semantics 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?

The description says it groups operations into a product, which conveys what a product is conceptually, but it never states the actual action verb ('create') or scope. It does not distinguish this from update_product, delete_product, or list_products beyond the title.

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

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

No indication of when to use this instead of update_product or how a product relates to operations assigned via assign_operation_to_product. There are no prerequisites, alternatives, or exclusions mentioned.

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 write profile (readOnly=false, destructive=false, non-idempotent, closed-world), so the description only needs to add context. 'The team replies by email' is genuinely useful — it signals the operation is asynchronous and produces no in-band result — but nothing is said about auth requirements, whether attachments must already be uploaded, or what happens on failure.

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 compact sentence with zero filler, and the core action is front-loaded. It is arguably too sparse to structure expectations for a five-parameter write, but nothing in it is wasted.

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

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

For a write tool with no output schema, the description should at minimum say what the agent gets back and how the ticket is identified afterward. 'The team replies by email' covers part of that, but the relation to list_support_tickets and the meaning of the organizationId approval requirement are left to 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 80%, so the schema already explains body, subject, type, attachments and the 'Approved workspace id only' constraint on organizationId. The description adds no extra parameter meaning, 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?

Clear verb+resource: 'Send a support request' tells the agent exactly what is created. However, it does not distinguish itself from the sibling list_support_tickets, nor does it say the ticket is scoped to a workspace/organization.

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

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

There is no guidance on when to file a ticket versus using another channel, no mention of prerequisites (e.g. approved organizationId), and no hint about which of the four `type` values is appropriate for a given situation.

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 state readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that — no URL expiry, no size limits, no auth requirements, and nothing about the fact that calling it repeatedly produces different URLs (consistent with non-idempotent but unexplained).

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?

It is short with no filler, but it is a grammatical fragment ('A presigned upload URL...') rather than a front-loaded statement of action and result. Brevity here reflects under-specification rather than tight editing.

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

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

There is no output schema, so the description should carry the essential return behavior — that the URL is time-limited, what HTTP method and headers the client must use, and whether the operation association is implicit. None of that is present, leaving the agent without the information needed to actually complete an upload.

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 fileName, contentType, size and organizationId are documented in the schema and the baseline is 3. The description mentions 'file input' generically but adds no semantics for organizationId or contentType beyond what the schema already says.

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

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

The description names the resource (a presigned upload URL) and ties it to a file input of an operation, so the agent can infer it generates a URL for uploading a file. However, it is a sentence fragment with no verb, and 'operation' is unexplained jargon that leaves the exact outcome slightly ambiguous.

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

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

There is no indication of when to call this versus anything else, no mention of the required follow-up (e.g., PUT the file bytes to the returned URL), and no prerequisites such as needing an existing operation. The agent is left to guess the workflow entirely.

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-readonly, non-idempotent, non-destructive write. The description adds little beyond stating it publishes a remote HTTP API; it omits side effects, validation behavior, error conditions, or what happens with duplicate slugs.

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 single sentence is front-loaded and free of waste, but given the tool's complexity it is too terse and does not earn its place by adding needed context.

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 creation tool with 8 parameters, nested objects, and no output schema, the description is severely incomplete. It does not explain what 'operation' means, how the remote URL is used, required fields, or expected behavior.

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

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

The description does not mention any of the 8 parameters, and with only 63% schema coverage many nested fields (e.g., execution.remoteUrl, httpMethod, secretHeaders, organizationId) lack description elsewhere. The description fails to compensate.

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 says 'Publish a remote HTTP API as an operation', which gives a verb and resource, but the term 'operation' is ambiguous and not clarified. It does not clearly distinguish from siblings like update_user_api or call_op.

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

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

No guidance is provided on when to use this tool versus alternatives such as update_user_api or create_api_key. There are no conditions or exclusions mentioned.

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 explicitly says the account is permanently closed and the workspace and its data are deleted, which is destructive behavior. The annotations declare destructiveHint=false, directly contradicting the description's central warning.

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 confirmation instruction is front-loaded and every clause carries useful information about permanence, restore options, billing, and store notice handling. It is dense but appropriately sized for a destructive account operation.

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

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

Given the absence of an output schema and the high schema coverage, the description covers the important operational context: confirmation, permanence, recovery, plan cancellation, store notice behavior, and authorization. The main gap is the contradiction with the destructiveness annotation rather than missing task details.

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

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

Schema coverage is 100%, so all three parameters are already documented in the schema. The description adds some operational context around confirmToken and owner-only access, but it does not meaningfully expand on workspaceName or organizationId beyond the schema.

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

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

The description states a specific verb and resource: permanently closes the account and deletes the workspace plus its keys, APIs, functions, and data. It is clearly an account-level destructive operation, though it does not explicitly differentiate itself from sibling deletion tools.

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

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

It gives explicit operating conditions: ask the user to confirm the workspace name, never decide for them, and note that the caller must be the owner. It does not name alternative tools or when not to use this one, so it falls 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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds the confirmToken workflow requirement, which is useful context beyond annotations, but does not explain irreversibility or what happens to associated 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 short sentences, both front-loaded and free of filler. The deletion action and the confirmation prerequisite are stated immediately with no unnecessary 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 covering safety and a fully described schema, the description is minimally adequate. However, it could better explain the confirmation flow and consequences of deletion, especially since no 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 schema already documents slug, confirmToken, and organizationId. The description reinforces that confirmToken is needed, but does not add syntax, source details, or constraints beyond what the schema provides.

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

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

The description states a clear verb and resource: deletes a function. It aligns with the tool name/title and is distinguishable from get/list/update hosted function tools, though it does not explicitly say 'hosted' or differentiate among delete siblings in the description itself.

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

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

The description gives only a prerequisite ('Needs a confirmToken') but does not explain when to use this tool versus alternatives such as update_hosted_function or delete_account. It leaves usage context to inference.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds valuable context beyond that: operations are reassigned to the default product rather than orphaned, and a confirmToken is required. It stops short of stating permissions or irreversibility of the deletion itself.

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 clauses with zero waste, front-loading the destructive action and its consequence before the prerequisite. Every phrase earns its place.

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

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

For a destructive three-param tool with full schema coverage and annotations carrying the safety hints, the description covers the critical side effect and the confirmation requirement. It omits permissions and what a rejected confirmation returns, but nothing essential to a correct call is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including the confirmToken's origin. The description reinforces that a confirmToken is needed but adds no format or edge-case detail beyond what the schema 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?

States a specific verb and resource ("Deletes a product") and adds the important side effect that its operations move to the default product. It is clearly distinguishable from siblings like update_product, create_product, and list_products, though it doesn't name them 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?

Mentions the confirmToken prerequisite, which hints at a confirmation workflow, but there is no explicit when-to-use guidance, no when-not conditions, and no reference to alternatives. An agent must infer that this is the destructive counterpart to update_product.

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 safety is covered structurally. The description adds the genuinely useful fact that a confirmation token is required, but stays silent on irreversibility, cascade effects (proxy config, keys, connections tied to the API), and whether an organizationId lets an admin delete others' APIs.

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 followed by the hard prerequisite. No filler, though the second sentence is telegraphic to the point of omitting necessary 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?

This is an irreversible destructive mutation with no output schema and no annotations covering permissions or side effects. The description does not say deletion is permanent, what else gets removed, or who may invoke it — an agent could easily call it with the wrong expectations.

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 explains that confirmToken comes from the CONFIRMATION_REQUIRED reply and organizationId is an approved workspace id. The description names confirmToken but adds no meaning beyond the schema, 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 ("Deletes") and resource ("a published API"), which is more than a tautology. However, it never uses the term "user API" that the tool name and the create_user_api/update_user_api/list_user_apis siblings establish, so an agent must infer whether this touches API keys, hosted functions, or the product-level API. No sibling differentiation is offered.

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?

"Needs a confirmToken" hints at a two-step confirmation flow but the description never states when to call this versus update_user_api, delete_hosted_function, or revoke_api_key, nor what prerequisites (ownership, org admin) apply. Usage is implied only by the verb.

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, destructiveHint=false, so the safety profile is known. The description adds nothing beyond that: no mention that secrets are stored/attached to the function, no timeout semantics, no statement about what happens on duplicate slug/name given idempotentHint=false, no deployment/runtime behavior. For a 10-parameter write operation with a secrets object, this is a substantive gap.

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?

It is one front-loaded sentence with no filler, so there is nothing wasteful. But at this length it is terse to the point of under-specification rather than genuinely concise for the operation's complexity.

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

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

A tool with 10 parameters, a nested inputFields schema, a secrets map, no output schema, and no return-value documentation gets a single seven-word sentence. Nothing explains the secrets handling, the input-field contract, timeout units, or what a successful deployment returns (function id? slug?). Grossly inadequate for the stated complexity.

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

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

Schema coverage is only 60%, and even the described fields have near-placeholder text ("Source", "Name", "Slug", "About"). Four parameters — tags, secrets, timeoutMs, and the nested inputFields — are undocumented in both schema and description, and inputFields defines the function's callable signature, which is critical. The description contributes zero parameter semantics.

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

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

"Create a function from code" gives a verb (create) and a resource (function), so the basic action is inferable. But it never says "hosted function," never distinguishes itself from create_product/create_user_api, and "from code" leaves the deployment target ambiguous. An agent must infer from the tool name alone that this is the hosted-function deployment path.

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

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

No guidance on when to use this versus update_hosted_function (for existing functions), delete_hosted_function, or list/get_hosted_functions. No prerequisites, no mention of whether a slug collision fails or updates. The agent gets no routing signal beyond the name.

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

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

Annotations cover the safety profile (not read-only, not idempotent, openWorld false), and the description adds a trait they do not: that revocation is immediate and gated behind a confirmToken. It still omits whether access tokens are invalidated, whether the action is reversible, or what a failure looks like.

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, no filler, with the action and its immediacy front-loaded before the token prerequisite. Every clause carries information.

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

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

For a non-idempotent mutation with no output schema and no annotations about confirmation, the description is adequate but thin: it does not explain the CONFIRMATION_REQUIRED round-trip or the effect on the app's grants. The schema fills in sourcing of both parameters, which keeps it at a minimum-viable level.

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

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

Schema description coverage is 100%, so both clientId and confirmToken are already documented in structured form. The description only re-asserts confirmToken as required, adding no format or sourcing detail beyond the schema.

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

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

States a specific verb and resource ("Revokes a connected app") and adds an immediacy qualifier, which distinguishes it from revoke_api_key and revoke_invite via the "connected app" object. It never names those siblings explicitly, so the differentiation is implicit rather than stated.

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?

"Needs a confirmToken" implies a two-step confirmation flow and, together with the schema's "Client id from list_connections", signals the prerequisites. It does not say when to prefer this over revoke_api_key/revoke_invite or when not to call 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?

Beyond the annotations, the description discloses meaningful behavior: keys are returned as prefixes only (a privacy boundary), call logs are capped at 90 days, and large exports come back as a download link rather than inline data. It does not explain why readOnlyHint is false (presumably an export artifact/job is created) or whether exports are rate-limited, so it falls short of 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?

Two tight sentences with no filler; the content inventory leads and the download-link behavior follows. The opening is a bare noun phrase rather than a verb, which slightly weakens front-loading of purpose.

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

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

With no output schema, the description does its job in sketching the response shape (JSON or download link) and the 90-day window. However, it omits permission requirements, whether the export is a heavy/async operation, and when not to use it, leaving gaps for a data-extraction 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 there is only one optional parameter, whose schema description ('Approved workspace id only') already carries the constraint. The tool description adds nothing about the organizationId, 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?

The description enumerates exactly what a data export contains (profile, workspace, members, keys with prefixes only, BYO APIs, hosted functions, products, 90 days of call logs), so the resource and its scope are unmistakable. It falls short of 5 because it is a noun list without an explicit verb and never tells the agent how this aggregated export differs from the many list_* siblings (list_members, list_api_keys, list_call_logs).

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

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

There is no statement of when to reach for this bulk export instead of the individual list_* tools, and no prerequisites (e.g., that it requires workspace ownership or a specific plan) are given. An agent must infer the use case from the name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds only a flat list of content areas; it does not say whether the result is scoped to the caller or to the given organization, what happens when organizationId is omitted (it is optional), or whether usage figures are current-period or lifetime.

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?

It is short and front-loaded with no filler, but the terseness is under-specification rather than economy — a four-noun list with no verb or object. Every word 'earns its place' only in the sense that there are so few of them.

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

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

With no output schema, the description must convey return content, and naming plan/role/usage/workspace does that at a high level. For a read-only aggregator with one well-documented optional parameter, this is minimally adequate, but it leaves the caller guessing about scope and freshness.

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 carries a meaningful constraint ('Approved workspace id only.'). The description adds nothing about the parameter, which is acceptable at this coverage level, though it misses the notable fact that the parameter is optional.

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 enumerates what the summary contains (plan, role, usage, workspace) but supplies no verb — it reads as a fragment restating the title 'Account summary'. It is distinguishable in spirit from siblings like get_usage or billing_status only by inference, since those overlapping concerns are never addressed.

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

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

No when-to-use guidance is given, despite siblings such as get_usage, billing_status, get_profile and list_plans covering closely overlapping ground. An agent has no stated basis for choosing this aggregator over the narrower tools.

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

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

Annotations declare readOnlyHint=false, so the agent knows this is not a pure read, but the description does not say what side effect occurs, whether repeated calls create duplicate connections, or whether auth/workspace scoping is required. It also doesn't say what the agent receives back (presumably URLs), which is the whole point of the 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?

One short, front-loaded sentence with no filler. It is efficient, though the brevity comes at the cost of the missing scope and return-value information noted elsewhere.

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

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

With no output schema and a tool whose purpose is to hand back install links, the description should at least say what is returned and in what form. Combined with no usage guidance and no disclosure of the non-read-only side effect, the definition leaves too much to inference for an agent to call it confidently.

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 optional 'agent' parameter is documented as 'Optional agent id', so the schema carries the load. The description's client list (Claude, Cursor, VS Code...) hints at what agent values mean but never explicitly connects those names to the parameter, so it adds only marginal value.

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

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

The description names the resource (install links) and enumerates supported clients (Claude, Cursor, VS Code, Claude Code, Codex, OpenCode), so the domain is clear. But the verb is 'Install links', which is ambiguous — the tool name get_connect_links suggests it returns links rather than installing anything, and the description never says it retrieves a URL or linkset. It also doesn't distinguish itself from nearby siblings like list_connections or disconnect.

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

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

There is no when-to-use guidance, no prerequisite statement, and no mention of alternatives such as list_connections or disconnect. The agent must infer entirely from the name and the client list when this tool applies.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered by structured data. The description does add one real behavioral fact beyond that: the function's source code is returned, which matters for payload size and sensitivity. Nothing about permissions, error cases, or code size limits.

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

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

The single sentence is front-loaded and free of waste, but it is under-specified rather than concise: a four-word fragment for a tool with a required identifier and an optional workspace parameter leaves the reader with nothing to act on.

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

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

No output schema exists, so the description carries the burden of describing the return value; it says only "including its code" and omits response shape, error behavior for an unknown slug, and the meaning of organizationId scoping. For a retrieval tool with two parameters this is thin.

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 3 applies, but the schema descriptions are near-tautological ("Slug", "Approved workspace id only."), and the description does nothing to clarify that slug identifies a hosted function or what "approved" means for organizationId. It neither compensates nor misleads.

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?

"One function including its code" conveys that a single hosted function is retrieved and that the code payload is included, which the name alone doesn't say. But it lacks an explicit verb and never says retrieval is by slug, so the purpose is only inferred from the name/title rather than stated.

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

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

No indication of when to use this versus list_hosted_functions, update_hosted_function, or delete_hosted_function, all of which are close siblings. There are no preconditions, no exclusions, and nothing tying the tool to a workflow.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety and side-effect profile are covered. With no output schema, the description adds real value by naming the returned fields, but it says nothing about failure modes (e.g. what happens when the workspace id is not approved).

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 eight-word sentence with zero filler, and the most important fact (whose profile) is front-loaded. The terseness is efficient rather than padded, though it shades into under-specification.

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

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

For a simple read tool with full annotation coverage, the description is mostly sufficient and usefully compensates for the missing output schema by listing return fields. The notable gap is the optional organizationId: an agent cannot tell from the description whether omitting it defaults to the current workspace or returns profiles across workspaces.

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 optional parameter and schema coverage is 100%, so the schema already documents organizationId. The description does not mention it at all and does not clarify the ambiguous 'Approved workspace id only' constraint or the behavior when it is omitted, so no meaning is added beyond the schema.

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

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

The description enumerates the returned fields (name, email, workspace, role), and 'Your' makes clear it reads the authenticated caller's own profile rather than an arbitrary member's. It does not, however, name the action explicitly or distinguish itself from the sibling update_profile, which an agent could 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?

There is no statement of when to call this versus update_profile, get_account_summary, or list_members, and no guidance on the optional organizationId case. 'Your' weakly implies self-scoped read usage, but no condition or alternative is spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only a vague statement about the config's content and says nothing about scoping to the organization, whether values are masked/secrets, or the return shape, so it contributes little beyond the structured fields.

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?

It is extremely short and there is no padding, but it is a fragment rather than a structured statement, and the brevity comes at the cost of a clear verb and lead-in. Nothing is wasted, but very little is delivered.

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

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

With no output schema, the description is the only place an agent could learn what a 'proxy config' returns (URL fields, masking of secrets, empty state). For a read tool with an optional scoping parameter, that gap is not covered anywhere else.

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 optional parameter has 100% schema description coverage ('Approved workspace id only.'), so the baseline is 3. The description adds no extra meaning about what organizationId scopes or what happens when it is omitted.

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 is a bare noun phrase, 'Proxy URLs used for outbound requests', with no verb stating what the tool actually does (retrieve? describe?). It does hint at the content of the config, but an agent must infer the read action from the name and title rather than reading it here, and it never distinguishes itself from sibling set_proxy_config or test_proxy_config.

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

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

There is no when-to-use guidance at all and no mention of the obvious alternatives (set_proxy_config to change it, test_proxy_config to validate it). The agent is left to infer usage entirely from the tool name.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only that the result concerns the user's referral link and earnings; it does not explain permissions, scope, or return structure beyond that minimal 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?

The description is a two-word noun fragment rather than a structured sentence. It is not bloated, but it is under-specified rather than concise, and it lacks front-loaded actionable detail.

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

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

For a simple read-only tool with one fully documented optional parameter and no output schema, the description gives a minimal indication of what is returned. It is adequate at the minimum-viable level, though it could clarify the relationship between referral link, earnings, and the organization context.

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

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

Schema description coverage is 100%, and the single organizationId parameter is documented as 'Approved workspace id only.' The description adds no parameter-specific detail, but the baseline is 3 when the schema fully carries parameter semantics.

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

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

The description 'Your referral link and earnings.' identifies the resource and suggests the returned content, but it does not state an explicit verb or action. It distinguishes itself somewhat from update_referral_ui_state by focusing on the user's own link and earnings, but the purpose remains inferred rather than clearly stated.

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

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

There is no guidance on when to use this tool, no prerequisites, and no mention of alternatives such as update_referral_ui_state. The agent is left to infer usage from the tool name and description alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the scope of data returned (limits, trial cap, per-key and per-client breakdowns), which is genuinely useful context. It says nothing about cost of the call, caching/staleness of usage counters, or whether organizationId changes the response scope.

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 sentence with no filler, and the core metric (units used and remaining) is front-loaded. It is a noun phrase rather than a verb sentence, which slightly weakens the lead, but nothing is wasted.

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

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

With no output schema, the description must convey the shape of the response, and it does so by enumerating the reported dimensions. For a simple read-only report tool with a single optional parameter, that is close to sufficient; the missing piece is how organizationId scopes the result.

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 optional organizationId is documented as 'Approved workspace id only.' The description adds no information about what that parameter changes in the result or what happens when it is omitted. Baseline 3 applies since 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?

Names a specific resource (usage/quota) and enumerates exactly what is reported: units used and remaining, per-minute limits, trial cap, compute and hosted-function usage, with breakdowns by key and connected client. That is a clear, content-level statement of purpose. It does not, however, distinguish itself from sibling billing_status or get_account_summary, which plausibly overlap.

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

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

There is no guidance on when to call this versus billing_status, get_account_summary, or list_api_keys. The description describes the payload but never states the situation that selects this tool, leaving the agent to infer from sibling names alone.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds the genuinely useful quota cost (1 unit of monthly quota per call) and the public-only constraint, but says nothing about failure modes for nonexistent or private repos.

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 the purpose and returned fields front-loaded and no padding. The second sentence carries a garbled fragment ('upAPI operation') that slightly muddies the quota-cost point but does not obscure it.

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

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

For a simple two-parameter read tool with no output schema, the description tells the agent what the call returns and what it costs. Missing only error/edge-case expectations, which is a minor gap at this complexity.

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

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

Schema description coverage is 100% and both parameters are documented in the schema (owner as user or org, repo name). The description adds no further meaning about parameter formats or constraints, 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 ('Fetch metadata') and resource ('public GitHub repository via the REST API'), and enumerates the metadata fields (stars, forks, topics, license, dates). The resource is unique among siblings such as wikipedia_article_get and web_search_post, though no explicit sibling contrast is drawn.

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?

Implied usage only: 'public' repository signals private repos are out of scope, but there is no explicit when-to-use guidance, no prerequisites (e.g., auth requirements), and no alternatives named among the many sibling tools.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false; the description adds the meaningful context that an actual email is dispatched, making the external side effect explicit. It stops short of noting that a repeat call sends a duplicate invitation 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 clauses with the safety-critical directive front-loaded and no filler. The first clause restates itself slightly ('who to invite and with which role' / 'never choose for them'), but the redundancy is minor and reinforces the constraint.

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 mutation with full schema coverage and annotations, the description covers the confirmation requirement and the email side effect. It omits what happens if the invitee is already a member or already invited, and what role the caller must hold to invite an admin — relevant for a single-shot, non-idempotent mutation.

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

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

Schema coverage is 100%, so the schema already documents all three parameters and the baseline would be 3. However, the description says the invite role is 'admin or owner' while the schema enum only allows 'member' or 'admin' — an agent following the prose could submit an invalid value, so the description actively misleads rather than adding value.

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 ('Emails an invitation') plus the role scope, so the action is immediately clear. It does not distinguish itself from siblings like accept_invitation, revoke_invite, or list_invites, so an agent has no explicit routing cue.

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?

'Ask the user who to invite and with which role; never choose for them' is a strong directive about how to invoke, but it is not guidance on when to use this tool versus alternatives such as create_user_api or list_members. Usage is implied rather than framed against siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description's only added context is the returned field list, which is thin; it says nothing about whether secret key material is omitted, whether results are paginated, or how the optional organizationId scope affects the result set.

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?

It is short with no wasted words, but it is an under-specified fragment rather than a front-loaded statement of purpose. The brevity reflects missing information (no verb, no scope) rather than disciplined concision.

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

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

For a simple read tool with full schema coverage and clear annotations, the bar is lower, but the description still omits what an agent needs: that it lists API keys (vs. other resources), whose keys are returned by default when organizationId is omitted, and that secret values are not exposed. Those are meaningful gaps for a credential-listing 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 single organizationId parameter is documented in the schema as 'Approved workspace id only.' With full schema coverage and one parameter, the baseline of 3 applies; the description adds no additional meaning about the parameter's behavior.

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 is a noun-phrase fragment ('Keys with name, prefix, scopes, last used') that restates the title rather than stating a verb+resource action. It adds a field list but never says 'lists API keys for the caller/workspace', so the agent must infer the operation from the tool name alone.

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

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

There is no guidance on when to use this versus create_api_key, revoke_api_key, rotate_api_key, or list_user_apis, all of which appear as siblings. No prerequisites, no exclusions, no mention of whether it returns keys for the whole org or just the caller.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered elsewhere. The description adds useful context by naming the returned fields and implying a recency window, but says nothing about ordering, default page size, or how far back 'recent' reaches.

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

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

A single short fragment with zero waste and the key noun front-loaded. It is efficient, though the missing verb makes it slightly less self-explanatory than it could be at the same length.

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 four optional params, no output schema, and a read-only annotation set, the description does partial duty by naming returned fields in place of a return schema. It still omits pagination behavior, default ordering, and the recency window, which an agent needs to interpret results correctly.

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

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

Schema description coverage is 100%, so page, status, operation and organizationId are already documented in the schema. The description's mention of status/caller/cost loosely maps to the status filter but adds no format, default, or interaction detail beyond structured data — baseline 3 applies.

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

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

The description identifies the resource (recent operation call logs) and the fields returned (status, caller, cost), but it is a noun phrase with no verb and no scoping. It does not distinguish this from siblings like search_ops or call_op, which an agent could easily confuse with a log-listing tool.

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

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

There is no guidance on when to use this versus search_ops or call_op, no mention of prerequisites, and no statement of what it excludes. The only hint is the word 'recent', which implies a bounded window but never states it.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and a closed-world scope, so the safety profile is fully covered. The description adds a small amount of context by indicating the payload includes app identity plus last-run timestamps. It says nothing about ordering, volume, or whether disconnected apps appear.

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

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

A single short clause - tightly scoped and front-loaded with the resource. It is a fragment rather than a complete sentence, and the value detail trails slightly, but there is no waste.

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

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

With no output schema, the description is the only source for what comes back, and it gives just one field hint (last run). For a simple zero-param list tool that is close to adequate, but pagination, ordering, and the scope of 'connected' are left unstated.

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

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

The tool takes zero parameters, so the schema is trivially complete and the description has no parameter semantics to carry. Baseline 4 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?

Names a specific resource - AI apps connected to this account - and adds a detail about content (last run time), so an agent knows it is an inventory read. It does not distinguish itself from near-neighbors like get_connect_links, list_api_keys, or list_granted_scopes, which an agent 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?

There is no when-to-use guidance, no mention of the natural counterpart tool (disconnect), and no indication of when another listing tool would be the better choice. Usage must be inferred entirely from the name.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds essentially nothing beyond that: no indication of whether results reflect granted vs. requested vs. available scopes, or how stale they may be. It restates the resource without new behavioral context.

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

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

It is a single short sentence with no padding, which suits a zero-argument getter. However, it is a noun phrase rather than a front-loaded statement of what the tool does, and 'tiers' is undefined, so brevity comes at the cost of clarity.

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

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

With no output schema, the description carries the burden of explaining the return value, and it does not — the shape of the tiers/scopes result, whether it includes pending requests, and its relation to request_scopes are all unstated. For a no-param read tool this is thin even though the call itself is trivial.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the schema is empty and closed. Baseline 4 applies since no parameter semantics are needed.

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 fragment names the resource it exposes (tiers and scopes held by this connection), so an agent can infer it is a read of granted permissions. But it lacks a verb and never says 'list' or 'returns', and 'tiers' is ambiguous next to siblings like list_plans or billing_status. The purpose is recognizable but not stated as an action.

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

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

No guidance on when to call this versus related siblings such as request_scopes, get_account_summary, or list_connections. The only hint is the phrase 'this connection', which implies a current-connection scope but never states prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that — no mention of scoping to the caller's organization, result ordering, pagination, or whether undeployed functions appear.

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 words are concise but amount to under-specification rather than efficient communication. There is nothing to front-load because almost no information is conveyed.

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 list tool with no output schema, the description should at least indicate what is returned and whether results are scoped or paginated. None of that is present, leaving the agent to guess.

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

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

There is a single optional parameter with 100% schema description coverage ("Approved workspace id only"), so the schema does the heavy lifting. Baseline 3 applies, though the description adds no meaning about how organizationId affects the listing.

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?

"Your deployed functions." is a noun phrase that essentially restates the tool name and title without a verb or scope. It does not distinguish the tool from siblings such as get_hosted_function or list_user_apis beyond the implicit plural.

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

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

No indication of when to use this versus get_hosted_function (single function) or list_user_apis. The agent must infer from the name alone that this is the enumeration variant.

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 a safe, idempotent, closed-world read, so the description's burden is lower. Beyond that it adds only 'Pending', with no mention of scoping, pagination, ordering, or what happens when the optional organizationId is omitted.

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 words are technically concise, but the dimension rewards appropriately sized and front-loaded information. This is under-specification rather than economy: the one useful qualifier ('Pending') is not developed into anything an agent can act on.

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

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

For a list tool with an optional org parameter and no output schema, the description should at least clarify scope, pending definition, and whether results are paginated. It supplies none of these, leaving the agent to infer behavior from the name and annotations alone.

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 is documented as an approved workspace id, so the schema already carries this information. The description contributes nothing about the parameter, which is acceptable at baseline but not additive.

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 is essentially a restatement of the name and title ('list_invites' / 'List invites'), adding only the status qualifier 'Pending'. It does not state a verb or clarify what an invite record contains, and it does nothing to distinguish this from siblings such as list_members or revoke_invite.

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

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

There is no guidance on when to call this versus related tools like accept_invitation, revoke_invite, or invite_member. The word 'Pending' implies a filter but the description never says whether it lists only the caller's invites, a workspace's invites, or when to use it at all.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds nothing beyond that — no indication of whether results are paginated, whether the optional organizationId widens or narrows scope, or what a member record contains.

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?

It is short, but this is under-specification rather than conciseness: a four-word fragment that conveys almost nothing an agent could not read from the tool name. Nothing is front-loaded because there is nothing to front-load.

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

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

The tool is simple (one optional param, rich annotations, no output schema), so the description needn't be long, but it still leaves open whether the call is scoped to the caller's workspace by default and what member/role fields come back.

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 (organizationId) is documented as 'Approved workspace id only'. The description adds no meaning about when to supply it or what omitting it returns, 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?

The fragment 'Workspace members and roles' hints at the resource (workspace members) and adds that role data is included, but it is a noun phrase with no verb and largely restates the title 'List members'. An agent can guess it retrieves members, but the description never explicitly says 'list' or 'retrieve'.

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

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

There is no guidance on when to call this versus siblings such as list_invites, get_account_summary, or update_member_role, and no mention of prerequisites or scope. The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description's only added value is naming the returned concepts (price, monthly quota, limits), which matters because there's no output schema, but it says nothing about ordering, scope of results, or that organizationId restricts the listing.

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?

It is short with zero waste, but it is not a sentence — no verb, no front-loaded statement of action — so brevity here reflects under-specification rather than tight structure.

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

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

No output schema exists and the description never says what a call returns (all available plans vs. the current subscription) or that organizationId is optional. For the only entry point to plan/pricing data in this toolset, that omission leaves real ambiguity.

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

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

Schema description coverage is 100% and the single parameter already carries 'Approved workspace id only,' so the schema does the work. The description adds nothing about how organizationId scopes which plans are returned. Baseline 3 for high coverage.

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

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

The fragment 'Plans with price, monthly quota and limits' identifies the resource and hints at the fields returned, but supplies no verb and no scope (all plans? the org's current plan?). Against siblings like billing_status, upgrade_plan and manage_subscription, it doesn't clarify which is being listed.

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

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

There is no when-to-use guidance and no mention of alternatives. An agent choosing between list_plans, billing_status and upgrade_plan gets no routing signal at all.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive behavior, and closed-world scope, so the safety profile is covered. The description adds only a vague hint that each product includes its operations, without explaining pagination, filtering, or scope 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?

The description is extremely short, but it is under-specified rather than efficiently concise. It is a fragment without a clear verb or structure, so it does not front-load actionable 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 no output schema, the description should clarify what a product listing contains, whether results are paginated, and how organizationId affects scope. It only says "operations in each," leaving the return behavior and listing semantics largely unexplained.

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

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

There is one parameter, organizationId, and schema description coverage is 100%, so the schema already documents it. The description adds no parameter meaning beyond the schema, which is acceptable at the baseline level for a single fully described parameter.

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

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

The description is a noun fragment that largely restates the tool name and title. "Products and the operations in each" hints at returned content but does not state a specific verb or distinguish the tool from siblings like search_ops or create_product.

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

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

There is no guidance on when to use this tool versus alternatives such as search_ops, create_product, update_product, or delete_product. The agent must infer that this is a listing tool for products from the name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile needs no restating. The description adds nothing beyond that: no pagination behavior, no result ordering, no note that it is scoped to the caller's account or workspace.

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?

It is short, but the brevity comes from under-specification rather than efficiency — a four-word fragment with no verb and nothing front-loaded. Being terse is not a virtue when the tool's purpose never gets stated.

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

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

This is a simple read-only tool with full schema coverage and strong annotations, so it should be easy to complete. Even so, the description omits the core action and any behavioral context, leaving the agent to infer from the title alone.

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 optional parameter (organizationId) exists and its schema description ('Approved workspace id only.') is fully documented at 100% coverage, so the baseline is 3. The description contributes no additional meaning about when to pass or omit organizationId.

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 is a noun phrase fragment, 'Your earlier support requests.', which restates the title rather than stating what the tool does. It never says it returns or lists tickets, and gives no indication of scope (all tickets vs. one workspace's tickets) that would separate it from create_support_ticket.

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

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

There is no explicit when-to-use guidance and no mention of alternatives, even though create_support_ticket in the sibling list is the obvious counterpart. The word 'earlier' weakly implies historical retrieval, but nothing states exclusions or prerequisites.

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

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

Annotations already declare this as read-only, idempotent, non-destructive, and closed-world, so the description does not need to carry the safety profile. It adds useful ownership scoping ('you published to your workspace'), but says nothing about return shape, pagination, or ordering.

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

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

The description is extremely short and contains no filler, but it is a fragment rather than a structured tool description. It is concise yet under-specified, lacking the front-loaded verb that would make the statement self-contained.

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

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

For a simple read-only list tool with rich annotations and a fully described optional parameter, the minimum context is present. However, it does not explicitly clarify listing behavior, result scope, or how it differs from adjacent list_* tools, leaving clear gaps.

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

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

There is one optional parameter and schema description coverage is 100%, so the schema already documents organizationId sufficiently. The description adds no additional parameter meaning, which is acceptable given the high schema coverage but earns only the baseline.

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

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

The description identifies a specific resource class ('Remote-URL APIs you published to your workspace') but is only a noun phrase and does not explicitly state the listing action. The tool name and title supply the verb, so the purpose is inferable, but the description itself remains vague about what the tool does.

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

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

There is no guidance on when to use this tool versus siblings such as list_api_keys, list_hosted_functions, or create_user_api. The scope 'you published' is implied, but no explicit when/when-not or alternatives 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?

Adds real value beyond the annotations by disclosing consequences and timing: refund 'revokes access' and cancel takes effect 'at period end', plus the confirmToken gating. It doesn't explain resume/portal behavior or what the response contains, so it stops short of rich behavioral disclosure. Note the access-revocation disclosure sits in mild tension with destructiveHint=false, though it is framed as billing consequence rather than data destruction.

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 the action list front-loaded and the token requirement appended. Minimal waste, though the terse fragment style and the missing 'resume' leave the enumeration feeling slightly incomplete rather than polished.

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

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

With no output schema, the description should carry more of the return/error story (e.g., that confirmToken issues a CONFIRMATION_REQUIRED reply, what portal returns). It covers calling correctly for three of four actions but leaves resume and outcomes unexplained; annotations at least carry the safety profile.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds a relationship the schema doesn't state: which actions (cancel, refund) require confirmToken. The action enum itself is described only as 'Action' in the schema, so the prose enumeration is the main source of meaning for those values, though it omits resume.

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?

Enumerates concrete actions (cancel at period end, refund last payment, open billing portal), which is far more specific than the vague name. However, it omits the 'resume' action that the schema enum permits, and it doesn't explicitly distinguish this from the sibling billing_status or upgrade_plan.

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

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

Implies context by stating that cancel and refund require a confirmToken, which signals these are gated/destructive-flow actions. But it gives no explicit guidance on when to choose this over billing_status or upgrade_plan, and no preconditions such as which plan states allow a resume.

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, non-idempotent, non-destructive write. The description adds nothing beyond them: it doesn't say whether registering the same token twice creates duplicates (relevant given idempotentHint=false), whether an existing token for the device is replaced, or what response to expect.

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

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

A single front-loaded sentence with no filler. It is concise but arguably under-specified rather than efficiently complete.

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 tool with no output schema and a non-obvious idempotency profile, the description covers only the bare purpose. An agent cannot tell from it how duplicate registrations or token rotation are handled, which is exactly the information the structured fields don't supply.

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 token, provider (fcm/apns enum) and previousToken are already documented. The description doesn't add meaning, notably it never explains the rotation flow implied by previousToken, so it sits at the baseline.

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

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

States a specific verb and resource ('Register a device push token') plus the purpose (notifications), which is clearer than the title alone. It doesn't need much sibling differentiation since the only near-neighbor, remove_push_token, is the inverse verb, but it also does nothing to distinguish itself.

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

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

No indication of when to call this (e.g., on app launch, after login, when a token rotates) or when not to call it. There is no mention of the relationship to remove_push_token or of prerequisites like authentication.

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, openWorldHint=false, and idempotentHint=false, so the safety profile is largely covered. The description adds the confirmation-flow requirement, which is useful, but says nothing about reversibility, whether the member loses access immediately, or what happens to their data. Note that the annotation destructiveHint=false sits uneasily with an outright member removal, though the description itself does not contradict it.

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

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

Two short sentences with the action front-loaded and the prerequisite second. Nothing is wasted, though the second sentence is thinner than it could be for a tool gated by a confirmation token.

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 mutating tool with no output schema, the definition is adequate but thin: it does not say whether the confirmToken comes from a failed call to this same tool, what happens post-removal, or what errors to expect. The critical prerequisite is named, so an agent can proceed, but with gaps.

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

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

Schema coverage is 100%: userId, confirmToken (with its CONFIRMATION_REQUIRED origin), and organizationId (approved workspace only) are all documented in the schema. The description's mention of confirmToken only restates what the schema already explains, 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: 'Remove a member from the workspace.' That is clearly distinct from siblings like invite_member, list_members, update_member_role, and revoke_invite without needing to open the schema. It stops short of explicitly naming the nearest alternative (update_member_role), so it is not 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 only usage signal is the confirmToken prerequisite, which is implied rather than explained as a workflow. There is no guidance on when to remove vs. demote (update_member_role) or when removal is inappropriate, but the intended use case is inferable.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally, but the description adds nothing further. It does not say what happens when the token is unknown, whether removal is per-user or global, or what auth is 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?

A single short sentence with the action front-loaded and no wasted words. It is efficient, though it borders on under-specified for a tool with authentication and idempotency implications.

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 simple two-parameter tool with full schema coverage, annotations, and no output schema, the description is minimally sufficient. It is missing error/edge-case behavior and any indication of what unregistration affects, which keeps it from a higher score.

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

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

Schema description coverage is 100%, with both 'token' and 'provider' documented and the provider enum constrained to fcm/apns, so the schema carries full weight. The description adds no format or semantic detail beyond the schema, which is the baseline-3 case.

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 ('Unregister') and resource ('device push token'), making the operation unambiguous. It does not, however, mention the sibling register_push_token, which would have made the inverse relationship explicit for an agent choosing between the two.

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

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

There is no guidance on when to call this versus alternatives such as register_push_token or update_notification_prefs, and no stated preconditions. The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful context that the tool does not mutate anything itself but instead produces a link the user must click, which is the key behavioral nuance. It omits how long the link is valid, whether repeated calls return the same link, and what the user sees.

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

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

One sentence, no filler, and the substantive information (click-ready link, grants more tiers) is front-loaded. Nothing to trim.

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

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

For a one-parameter tool with no output schema, the description is close to adequate but leaves the most consequential detail open: what values 'tiers' accepts. Whether the returned link appears in the result body or elsewhere is also unstated, though the word 'Returns' implies it is the primary payload.

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 0% and the single property is an array of untyped strings described only as 'Tier'. The description says 'permission tiers' but gives no valid tier names, no format convention, and no indication whether these are cumulative or absolute. Since the schema carries essentially nothing, the description needed to compensate and does not.

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 concrete verb-plus-result: returns a click-ready link that lets the user grant additional permission tiers to the current connection. That clearly separates it from a listing tool like list_granted_scopes, though it never names a sibling. Slightly reduced because 'this connection' is not defined and the tool's own role (generate a URL vs. actually escalate permissions) takes a sentence to parse.

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

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

Usage is only implied: an agent infers it should call this when a call fails for insufficient permissions or when more tiers are needed. There is no explicit 'use when X', no mention of checking list_granted_scopes first, and no note that the user must actually click the link before the new scopes take effect.

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 real behavioral detail beyond the annotations: deletion is immediate (no grace period) and a confirmation token is required, implying a two-step CONFIRMATION_REQUIRED flow. But it directly conflicts with the annotation destructiveHint=false — permanently invalidating a credential is destructive, and an agent reading the annotations could invoke this without the caution the description implies.

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

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

Two short sentences with the destructive action and the key prerequisite front-loaded; nothing is padded. It is arguably over-terse rather than wasteful, which is penalized elsewhere rather than here.

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 irreversible credential-destroying mutation with no output schema, the description never explains the confirmation flow mechanics, what happens to in-flight requests using the revoked key, whether the action can be undone, or how it differs from rotate_api_key. Combined with the destructiveHint=false conflict, an agent lacks what it needs to call this safely.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including that confirmToken comes "From the CONFIRMATION_REQUIRED reply." The description's "Needs a confirmToken" usefully implies the token is conditionally mandatory even though the schema marks only keyId as required, but it says nothing about organizationId.

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?

"Deletes a key immediately" gives a specific verb (delete) and resource (an API key, per the name), which is enough to tell it apart from create_api_key, rotate_api_key and list_api_keys. It stops short of explicitly naming the sibling it replaces, but the action is unambiguous.

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

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

"Needs a confirmToken" signals a prerequisite and implies the confirmation flow, which is useful usage context. However, there is no guidance on when to revoke versus rotate a key, no statement about who may call it, and no mention of the org-scoped variant (organizationId) or what to do when the token is absent.

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-read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds the useful qualifier that only *pending* invitations can be revoked, but says nothing about what happens on an already-accepted invite, whether a re-invite is possible, or notification 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?

A single short sentence with no filler, and the key qualifier ('pending') is included up front.

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

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

For a simple two-parameter mutation with full annotation coverage, the description is adequate but thin: it does not cover failure modes (unknown/already-used invitation), whether the action is reversible, or any confirmation of scope beyond 'pending'.

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

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

Schema description coverage is 100%, so both parameters are documented in the schema, setting the baseline at 3. The description adds no extra detail on invitationId (e.g., format or where to obtain it) or on the organizationId scoping constraint that the schema flags as 'approved workspace id only'.

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 (cancel an invitation) and narrows scope to pending invitations, which distinguishes it from siblings like accept_invitation and invite_member. It does not explicitly name those siblings, but the action is unambiguous.

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

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

There is no explicit guidance on when to use this vs. alternatives such as remove_member or accept_invitation, and no mention of prerequisites (e.g., invite must be pending). Usage is only implied by the verb.

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-read-only, non-destructive, non-idempotent; the description adds genuinely new behavioral facts beyond them: the new key inherits the old key's scopes, the secret is returned only once (so it must be captured immediately), and the old key is NOT invalidated automatically. Missing only edge context such as rate limits or whether repeated rotation is allowed while the prior key lives.

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

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

One sentence, front-loaded with the action and the two facts that most affect correct use (secret shown once, old key still live). 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 only two fully-described parameters and no output schema, the definition covers what the tool produces (a secret, once) and the post-call state (old key still active). It would be complete at 5 with an explicit pointer to revoke_api_key for the cleanup step and any permission requirement.

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 keyId and organizationId are already documented ('Approved workspace id only'). The description adds no syntax, format, or constraint details about either parameter, 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 the specific effect: creates a replacement key with the same scopes and returns its secret. The 'old key keeps working until you revoke it' clause makes the rotation semantics unambiguous. It falls short of 5 because it never names the sibling tools it sits between (create_api_key, revoke_api_key), so the agent has to infer the distinction.

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?

Rotation intent is implied by 'replacement' and the note that the old key survives until revoked, but there is no explicit when-to-use-this-vs-create_api_key guidance and no stated prerequisites (e.g. permission to rotate, whether keyId must belong to the caller). Usage is inferable rather than instructed.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new context: the catalog's size and category taxonomy, and the shape of each match (slug, description, parameters, quota-unit cost) — important since there is no output schema. It does not state ordering or relevance behavior, which keeps it off a 5.

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

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

Three sentences, front-loaded with the purpose, then catalog scope, then return shape, then the next action. The category list is long but is load-bearing vocabulary rather than filler; nothing here is redundant with the schema or annotations.

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

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

For a read-only three-parameter search with no output schema, the description covers what it searches, how big the corpus is, what a result contains, what a call costs, and what to do with a hit. An agent has everything needed to invoke it correctly and act on the result.

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 earns an extra point by enumerating the eleven category names, which expands the `category` parameter's usable vocabulary beyond the schema's three examples. `limit` and query syntax remain fully delegated to the schema, which is appropriate.

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

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

States a specific verb and resource ("Find upAPI operations to call") and immediately scopes the corpus (128 operations across 11 categories). It also explicitly separates discovery from execution by pointing at `call_op`, so an agent can tell this apart from `call_op`, `web_search_post`, and `wikipedia_article_get` 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?

Clear when-to-use framing: search the catalog first, then "Run one with `call_op`." It also documents the browse-everything escape hatch (empty query). It stops short of an explicit when-not clause, e.g. skipping search when the slug is already known, but the sequencing guidance covers the main decision.

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=true, and destructiveHint=false, so the safety profile is covered. The word "Replace" usefully signals a full-overwrite of the existing list rather than an append, but the description does not say whether an empty list clears the config, how URLs are validated, or whether an in-flight connection drops on replacement.

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

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

A single front-loaded sentence with zero filler, so nothing needs trimming. It is concise to a fault: the brevity is what leaves the parameter and usage gaps unaddressed.

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 mutating config tool with two parameters, one of them entirely unmentioned in the description and only weakly described in the schema, this is under-specified. With no output schema the description should at least say what state results after replacement, and it does not.

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 only 50%: proxyUrls is documented as a bare "Proxy URL" item type, and organizationId only as "Approved workspace id only." The description compensates for neither — it never mentions organizationId scoping, ordering/precedence of URLs, or whether the array must be non-empty.

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 ("Replace") and resource ("proxy URL list"), which lets an agent distinguish this write tool from get_proxy_config and test_proxy_config by name alone. It stops short of explicitly naming those siblings as alternatives, so a 4 rather than 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?

There is no guidance on when to use this instead of test_proxy_config (to validate) or get_proxy_config (to inspect), and no prerequisites such as required permissions or whether the config takes effect immediately. "Replace" hints at full-overwrite semantics but no alternatives or exclusions are stated.

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

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

Annotations already disclose the safety profile (not read-only, not destructive, idempotent, closed-world), so the description only needs to add context. It says the tool checks whether a URL works, but it does not explain whether this makes a live network request, what side effects may occur, or what permissions are needed.

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

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

The description is a single front-loaded sentence with no wasted words. It is appropriately terse for a simple two-parameter 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?

The low-complexity schema and annotations cover much of the needed context, and the description states the basic check behavior. However, with no output schema, the description does not explain what a successful or failed test returns, and it leaves organizationId scope entirely to 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 the schema already documents both parameters. The description reinforces the required proxyUrl concept but adds no new meaning for organizationId or parameter formatting beyond what the schema provides.

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

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

The description uses a specific verb ('Check') and resource ('proxy URL works'), making the tool's purpose clear. It is distinguishable from get_proxy_config and set_proxy_config by implication, but it does not explicitly differentiate itself from those 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?

Usage is only implied: use this tool when you need to verify that a proxy URL works. There is no explicit when-to-use guidance, no exclusions, and no named alternatives such as get_proxy_config or set_proxy_config.

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 mutation safety (readOnly=false, destructive=false, idempotent=true), so the description's main added behavioral value is the partial-patch semantics for secrets ('Secrets you leave out of the patch are kept'). It does not explain merge/replace behavior for the other mutable fields, permissions required, or what the operation returns, leaving meaningful ambiguity for a mutation tool.

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

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

Two compact sentences: the first front-loads the field scope, and the second adds a non-obvious patch detail. There is no filler, and the most important content appears first.

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 tool with a nested patch object and no output schema, the description gives a useful field inventory and one key merge rule for secrets. It still leaves open whether omitted non-secret fields are retained or reset, what response to expect, and what the slug/organizationId constraints are.

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 67%, but the key 'patch' parameter is an undescribed nested object with additionalProperties=true; the description compensates well by enumerating the fields it can contain. However, the 'slug' parameter is documented only as 'Slug' and 'organizationId' only as 'Approved workspace id only.', so the description does not fully close the remaining gaps.

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

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

The description gives a specific mutation verb and enumerates the mutable fields (code, description, secrets, input fields, category, tags, timeout), which makes the operation's scope clear. It does not explicitly name the resource 'hosted function' or differentiate from siblings like update_user_api or update_product, relying on the title/name for that context.

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

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

There is no guidance on when to use this tool versus alternatives such as update_user_api, update_product, or delete_hosted_function, nor any stated prerequisites or exclusions. The only usage-adjacent information is the field list and the secrets merge note.

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=true, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that and beyond the schema's own enum — it does not say whether demotions are reversible, whether a member can change their own role, or what happens if the target is not in the org.

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

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

A single short sentence with zero filler and the key constraint (the two valid roles) front-loaded. It is efficient, though terse enough that it omits anything operationally useful.

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

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

For a mutation tool with no output schema, the description is too thin: it says nothing about permission requirements, the optional organizationId scoping ('Approved workspace id only'), or the outcome of a successful change. Annotations and schema cover structure but not the operational context an agent needs before mutating access.

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

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

Schema description coverage is 100%, so all three parameters (userId, role, organizationId) are already documented and the role enum is explicit. The description only restates the two role values and adds no format, defaulting, or scoping detail beyond the schema.

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

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

States a specific verb and resource ('Change a member') plus the exact role transition ('between member and admin'), which is enough to distinguish it from siblings like invite_member, remove_member, and list_members 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?

There is no guidance on when to use this versus alternatives (invite_member for a new person, remove_member to revoke access) and no stated preconditions, such as the caller needing admin privileges or the target already being in the organization.

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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the important nuance that the tool doubles as a read-only getter when the field is omitted — behavior the annotations alone would misrepresent. It does not mention permissions or what a read returns, so it stays at a solid 3.

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 filler, with the read/write duality front-loaded. The phrase 'the field' is mildly ambiguous given two parameters exist, which 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?

With only two fully documented params, no output schema, and rich annotations, the description has little burden. Still, it never says what a read returns or how this relates to the broader notification-preferences surface implied by its name, leaving a small but real gap for an agent deciding whether this tool covers its need.

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 goes beyond the schema by defining the semantics of omission: leaving out the toggle means read-only mode rather than 'no change'. That is real added meaning for a boolean optional parameter. It says nothing extra about organizationId, hence not a 5.

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 dual action (read or change) on a specific resource (in-app tips and prompts). It is clear enough to act on, though the scope wording drifts from the tool name/title ('notification preferences'), leaving some doubt about whether other notification settings are covered.

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 one concrete usage rule — omit the field to perform a read — which is genuinely useful for a dual-mode tool. However, it offers no context on when to reach for this tool versus adjacent config tools (update_profile, update_referral_ui_state, update_workspace) and no prerequisites beyond what the schema states.

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, destructiveHint=false, idempotentHint=true and openWorldHint=false, so the safety profile is covered elsewhere. The description adds nothing beyond that: no statement on whether this is a partial or full replacement, whether existing fields are preserved, what permissions are needed, or what happens if the product does not exist. Worse, 'rename or redescribe' implies either action alone, while the schema requires 'name' unconditionally.

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

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

A single short sentence, front-loaded with the verb. It is efficient but arguably undersized for a four-parameter mutation tool; there is room for one more sentence on required fields without bloat.

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?

Annotations cover the safety profile and the schema documents every parameter, but for a write operation with no output schema the description should say what a successful update returns or whether the whole record is replaced. Combined with the misleading 'or' framing against a schema that requires name, the definition is not complete enough to call confidently.

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

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

Schema description coverage is 100%, so the baseline is 3. The description loosely maps to 'name' and 'description' but says nothing about organizationId ('Approved workspace id only') or about the fact that name is mandatory even when only changing the description, which is the one non-obvious constraint an agent would want.

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 pair and resource ('Rename or redescribe a product'), which distinguishes it from create_product, delete_product and list_products in the sibling set. However, 'rename or redescribe' understates the tool: the schema also accepts organizationId, so the stated scope is narrower than the actual operation.

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

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

There is no when-to-use guidance, no prerequisites (a productId must already exist), and no mention of how this differs from create_product or update_user_api. The agent must infer the usage context entirely from the name and the sibling list.

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=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds nothing beyond that: it does not say whether omitted fields are left unchanged (partial vs full replace), whether the URL is validated or fetched, or what happens on failure — the key ambiguity for a two-optional-parameter 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?

One short sentence, front-loaded and free of filler. It is appropriately sized for a simple two-field update, though it is too terse to carry much 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 simple, non-destructive, idempotent update with fully documented parameters and no output schema, the description is minimally sufficient. It still leaves the partial-update semantics unstated, which matters because both parameters are optional.

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 both parameters are described there, so the schema carries the semantics. The description only restates the two field names, adding no format or validation detail beyond what the schema provides; 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 ('Change') and resource ('your profile'), and names the two mutable fields, so its purpose is immediately clear. It does not explicitly distinguish itself from the sibling get_profile, but the read/write distinction is implied by 'Change'.

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

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

No guidance on when to use this versus get_profile or update_workspace, and no note on prerequisites such as authentication. The agent must infer everything from the tool name.

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

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

Annotations already declare readOnly=false, idempotent=true and destructive=false, so the mutation profile is partially covered. The description adds nothing about what dismissing permanently suppresses, whether answering submits a response to a backend, or whether repeated calls change state — the very behavior an agent needs for a UI-state 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?

The single sentence is front-loaded and free of padding, but it is concise by omission rather than by discipline. Brevity here costs the agent the only channel it has to learn the patch format.

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

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

A mutation tool taking a free-form required object payload with no output schema is the hardest case, and the description supplies none of the missing structure. An agent can guess the operation but cannot construct a correct call from the definition alone.

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 50%, but the documented half is only organizationId ('Approved workspace id only.'). The required 'patch' parameter is an unconstrained object with additionalProperties=true and no description, and the description gives no hint about its shape, allowed keys, or how dismiss differs from answer.

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 pair of actions (dismiss, answer) against a specific resource (referral prompts), which is more informative than the title alone. It is not differentiated from the sibling get_referral, which reads the referral but is never mentioned here.

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

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

There is no statement of when to call this versus get_referral or the other referral/billing siblings, and no prerequisites such as an active referral prompt existing. The only guidance is the implied condition embedded in 'Dismiss or answer'.

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=true, and destructiveHint=false. The description adds genuinely new behavioral detail beyond that: omitted fields in the patch retain stored values, including secret headers, which tells the agent that a partial patch will not wipe secrets. It does not mention permission requirements or what the response returns.

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, with the partial-update rule front-loaded before the secret-headers caveat. Nothing could be removed without losing information.

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

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

For a mutation tool the annotations cover the safety profile and the description covers patch semantics, so the basics are present. However, with a nested open-ended `patch` object and no output schema, the definition leaves the agent without a field list or a description of the returned API representation — a meaningful gap for a write operation.

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

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

Schema coverage is 67%, but the two descriptions that exist are near-useless ('Slug' and 'Approved workspace id only.'). Critically, the `patch` parameter is a free-form object with additionalProperties=true and no field enumeration anywhere, so the agent cannot tell which fields are patchable. The description's note about omitted fields keeping stored values partly compensates but leaves the core parameter opaque.

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 — 'Change one of your published APIs' — which clearly separates it from create_user_api, delete_user_api, and list_user_apis. It does not explicitly name those siblings, so it stops short of full differentiation, but the intent is unambiguous.

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

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

There is no explicit when-to-use guidance, no prerequisites (e.g. ownership, published status), and no reference to alternatives such as create_user_api or update_hosted_function. The only implied usage is that the API must already exist.

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=true and destructiveHint=false, so the safety profile is covered. The description contributes the admin/owner permission requirement, which is genuinely useful context, but it says nothing about name collisions, failure modes, or whether the old name becomes available.

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

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

A single front-loaded sentence with zero filler; the permission qualifier is attached directly to the action statement.

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, fully documented, well-annotated rename operation this is close to sufficient; no output schema exists so return values needn't be explained. Still missing is behavior on duplicate names or an invalid organizationId, and the name/title vs. description scope mismatch (update vs. rename) is unresolved.

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

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

With 100% schema description coverage, both parameters (name with a 2-60 character constraint, organizationId "Approved workspace id only") are already documented in the schema. The description adds no extra semantics such as uniqueness of names, conflict behavior, or what an "approved" workspace id means.

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 ("Rename the workspace") that is easy to distinguish from sibling mutators such as update_member_role, update_profile and update_product. The only weakness is that the tool is named update_workspace while the description narrows the action to renaming, leaving open whether other workspace fields exist elsewhere.

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 parenthetical "(admin or owner)" gives a concrete authorization precondition for use, which is more than most mutation tools offer. However, it never states when to choose this over alternatives (e.g. invite_member, update_profile) or what to do when the caller lacks the required role.

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 mark this as non-read-only, non-idempotent and non-destructive, and the description usefully clarifies why: the call generates a checkout link rather than executing a purchase, so the write is deferred to the user. That resolves what the readOnlyHint=false would otherwise leave ambiguous. It omits whether the link expires, is single-use, or what it costs to invoke repeatedly.

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 and zero filler. The return-value statement comes first and the usage constraint immediately follows, so both the what and the how are 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?

With no output schema, the description does the right thing by saying the return value is a checkout link. Annotations cover the safety profile and the schema is fully documented, so the remaining gap is minor: nothing about failure modes such as a workspace already being subscribed.

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 both the plan slug source (list_plans) and the organizationId constraint are already documented in the schema. The description reinforces the plan parameter by requiring the user to pick it, but adds nothing about organizationId or valid slug format. Baseline 3 applies when the schema carries the semantics.

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

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

States a specific verb and resource: it returns a one-click checkout link for a plan. That is concrete enough to separate it from list_plans, which only enumerates plans. It stops short of naming the sibling it differs from (list_plans for the slug, manage_subscription for the billing action), so an agent must 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?

"Ask the user which plan; never choose for them" is an explicit precondition and a prohibition on agent autonomy, which is the most important usage rule for a purchase-adjacent tool. It gives no guidance on when not to use it (e.g. an already-subscribed workspace) or which sibling to call for billing changes.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive behavior, so the safety profile is covered. The description adds genuinely new operational context: the DuckDuckGo backend, the absence of browser/CAPTCHA overhead, and a per-call quota cost of 1 unit — the last being exactly the kind of rate/cost disclosure annotations cannot convey.

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

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

Two compact sentences with zero filler; the primary capability and its return shape are front-loaded before the backend/quota note. 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?

With no output schema, the description usefully characterizes the return payload (titles, URLs, snippets) and discloses the quota cost, which covers most of what an agent needs. It stops short of describing result ordering, pagination, or failure behavior, leaving a minor gap.

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

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

Schema description coverage is 100% and all three parameters (query, region, maxResults) are documented in-schema with defaults and bounds. The description adds no syntax, format, or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('Search the web') and names the return shape ('titles, URLs, snippets'), which is more than a restated name. It does not, however, distinguish itself from the sibling search_ops, which an agent could easily confuse with this tool.

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

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

The description gives context ('DuckDuckGo-backed — no browser, no CAPTCHA, fast') that implies when this is convenient, but never states when to use it versus siblings like search_ops or wikipedia_article_get, nor any exclusions. Usage is implied rather than directed.

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 safety (readOnly, idempotent, openWorld, non-destructive), so the bar is lower, and the description adds real context beyond them: it is a public REST call and consumes 1 unit of monthly quota per invocation, which is a material operational constraint. It stops short of describing failure modes (missing article, unsupported language) or throttling.

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

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

Two compact sentences with the core capability front-loaded, followed by the cost note. The internal operation identifier ('wikipedia-article.get') is arguably noise for an agent, but there is no wasted prose.

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

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

With no output schema, the description usefully enumerates the returned fields, and the schema plus annotations cover inputs and safety. The only gap is the absence of guidance on error/empty-result behavior for a two-param lookup tool, which is minor given the low complexity.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, and the baseline is 3. The description adds only a light hint that language is constrained to 'supported' languages, but contributes no syntax or format detail beyond what the schema supplies.

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

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

States a specific verb ('Fetch') and resource ('Wikipedia article summary') and enumerates exactly what the response contains (description + extract + thumbnail + coordinates), which no structured field provides. This is clearly distinguishable from siblings like github_repo_get or web_search_post, which target different resources.

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

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

Usage is implied by the tool's obvious subject matter (retrieve a Wikipedia summary), and the quota cost note gives a decision cue for high-volume callers. However, it never states when to prefer this over alternatives such as web_search_post for factual lookups, nor any exclusions.

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