4chems Platform — IUCLID, CHESAR & QSAR Toolbox hosting

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, but the description adds real extra context: the token is single-use, consuming it marks the invitation accepted, and a role assignment is created as a side effect. That single-use consumption detail is exactly the kind of behavior an agent cannot infer from the annotations.

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

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

Two tight sentences: purpose and effect first, then the usage condition and the consumption semantics. No filler, and the most decision-relevant information is front-loaded.

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

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

An output schema exists so return values need not be described, and the annotations cover the safety profile. What remains thin is failure behavior (invalid/expired/already-consumed token) and the nature of the authorization parameter, but for a two-parameter, single-effect call this is nearly complete.

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

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

Schema description coverage is 0%, so the schema supplies no meaning for either of the two parameters. The description partially compensates by explaining that the token is single-use and gets consumed, but it never explains the 'authorization' parameter (presumably a bearer credential) or where the token originates.

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 ('Accept a pending invitation') plus the consequence ('grant the invitee's first role assignment'), so an agent knows exactly what the call does. It doesn't explicitly name siblings like create_invitation or revoke_invitation, but readOnlyHint=false distinguishing a mutation is clear enough from the wording.

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?

'Call this when an invitee has a valid invite link and wants to join the tenant' gives a clear triggering condition. It lacks explicit exclusions (e.g., what to do if the invite is expired, or that revoke_invitation is the opposite operation), so it stops short of the 5 mark.

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

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

Annotations already declare non-readOnly, non-destructive, non-idempotent, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond them: the call requires the `admin` realm role, with the ADR 0016 correction noted. It does not say what happens on a repeat submission for an already-subscribed service, which the non-idempotent hint makes relevant.

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

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

Two front-loaded sentences: purpose and status first, trigger and auth note second. The ADR parenthetical is dense but earns its place as a precondition. No filler sentences.

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

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

An output schema exists, so return values need not be described, and annotations cover the mutation safety profile. However, for a non-idempotent write with 0% schema coverage on three required-ish parameters, the description leaves the agent without enough to construct a correct call (what identifies the service, what tenant_id defaults to).

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 three parameters exist, so the description must carry the load — but it only implies a 'service' value and says nothing about `service`, `tenant_id`, or `authorization` (including whether tenant_id defaults to the caller's tenant). The one genuinely helpful detail, the admin-role requirement, is auth context rather than 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?

States a specific verb and resource ('Request a new service subscription for the caller's tenant') plus the effect ('return its status'), which is enough to separate it from read-only siblings like list_tenant_services. An agent can tell what the tool does without opening the schema.

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

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

Names the trigger condition explicitly ('Call this when a tenant admin wants to add a service'), which is real routing guidance. It stops short of 5 because no alternative is named (e.g., create_self_service_tenant or list_tenant_services) and no when-not-to-use case is given.

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

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

Annotations only declare it is a non-read-only, non-idempotent mutation; the description goes well beyond that by disclosing the two side effects (invitation issued, request resolved), the required caller privilege level, the fact that the returned token is single-use and must be handed to the requester, and the exact 409 access_request.not_pending failure mode.

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

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

Three tightly packed sentences, front-loaded with the action and its effects, then the response contract, then the error condition. No filler or repetition of the title.

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

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

For a mutation with named side effects, a privilege requirement, and a single-use token return, the description covers what an agent needs to call it correctly and what to do with the result; the output schema can carry the payload shape. The one real hole is the undocumented authorization parameter.

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

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

Both required parameters (authorization, access_request_id) have 0% schema description coverage, so the description must carry them — and it explains neither. The phrase 'the request's tenant' loosely implies what access_request_id refers to, but authorization's format and expected value are entirely undocumented.

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 ('Approve') and resource ('a pending access request'), then spells out the two concrete effects: issuing a member invitation and resolving the request. This distinguishes it cleanly from siblings like dismiss_access_request, withdraw_access_request, and create_invitation.

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 the precondition that the caller must be admin or owner of the request's tenant, and the pending-state requirement implied by the 409 error. It also routes the requester side to accept_invitation. It stops short of explicitly contrasting with reject/dismiss siblings, but the when-to-use context is clear.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true), and the description adds genuinely new behavior beyond them: EU VAT ids are validated against VIES, the specific failure code billing.vat_check_unavailable is retryable by resubmission, and success returns 202 with an operation to poll. These async/external-validation/retry semantics are exactly the kind of context 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?

Three sentences, front-loaded with the what, then the when, then behavior; no filler. Slightly dense in the VIES/retry clause and mildly overlaps the schema body note about VAT-vs-country checking, but each sentence earns its place.

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

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

An output schema exists so return values needn't be explained, yet the description still notes the 202 + poll pattern. Combined with the safety annotations and the field enumeration, an agent has enough to invoke it, with the only real shortfall being the undocumented legal_entity_type/tenant_id 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 description coverage is only 33%, so the description must compensate, and it does list the main body fields (legal-entity name and type, VAT id, invoice address, invoice email, optional PO reference) and flags PO reference as optional. However, it omits format-level detail such as the legal_entity_type pattern, the tenant_id parameter, and the address sub-fields by name, leaving meaningful 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?

States a specific verb and resource ('Complete the tenant's billing details') and enumerates the data involved (legal-entity name/type, VAT id, invoice address, invoice email, PO reference). An agent can tell what the tool does at a glance, though it never explicitly contrasts itself with the read-only sibling get_billing.

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

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

Gives a clear triggering condition: 'Call this when the owner or a billing contact has the details.' That is real context, but it offers no explicit when-not guidance or named alternatives (e.g., get_billing to read, get_legal_entity_types to look up the legal-entity code).

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=false), so safety is largely covered. The description adds the meaningful constraint that the tenant is derived from the caller's verified email domain rather than supplied as a parameter, but it does not explain idempotent re-request behavior or what state the request lands in.

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 scoping rule, with no filler or redundancy.

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

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

An output schema exists, so return values need not be described. However, for a request-creation tool the description omits prerequisite conditions (verified domain), what happens on an unknown domain, and whether the request enters a pending-approval state — a few clarifying clauses would close the 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 coverage is 0% and the description never mentions the single required 'authorization' parameter, which is presumably a credential. With one undocumented required parameter, the description fails to compensate for the schema gap.

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

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

Specific verb (request) plus a scoped resource (access to the tenant owning the caller's verified email domain), so an agent understands this initiates an access request. It does not explicitly contrast with siblings like create_invitation or start_registration, but the resource framing is distinctive enough to disambiguate.

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, no prerequisites stated, and no alternatives named among siblings such as create_invitation, create_self_service_tenant, or start_registration. The caller must infer that this path applies only to users whose email domain matches an existing tenant.

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, non-idempotent, non-destructive, closed-world profile. The description adds genuinely new behavior: the response contains the raw single-use accept token — a security-relevant detail the annotations do not expose — and it discloses the pairing with accept_invitation. It omits permission requirements beyond the implied admin actor.

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 behavioral fact (invite + token) is front-loaded and the lifecycle hint follows. Nothing is redundant, though the second clause is only a pointer rather than added substance.

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

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

An output schema exists so the return payload need not be re-explained, and annotations cover the safety profile. But for a nested-body mutation with 0% schema coverage, the description leaves tenant_id and billing_contact semantics and the required authorization parameter entirely to inference, which is a real gap for correct invocation.

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

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

Schema description coverage is 0% for a 3-parameter nested body, so the description carries the full burden and mostly does not. It conveys that an email address and an access level are supplied, but says nothing about tenant_id (presumably defaulted to the caller's tenant), the billing_contact flag, or valid level values.

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 (invite/create), the resource (invitation), the target (an email address in the caller's tenant) and the access-level scope, plus what is returned. It distinguishes itself from list_invitations, revoke_invitation and accept_invitation by naming the accept-side counterpart, so an agent can place it in the invitation lifecycle 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?

"Call this when a tenant admin wants to add a new member" gives a clear triggering condition and an actor, and it routes the agent to `accept_invitation` for the next step. It stops short of stating when not to use it (e.g., when a member already exists), so it is not a full when/when-not rule.

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 behavior beyond annotations: the trial lasts exactly 7 days, ttl/expires_at are silently ignored, and it enumerates the error taxonomy (auth.email_not_verified, tenant.attestation_required, tenant.free_mail_domain, tenant.domain_exists, trial.exists_for_domain). This explains the non-idempotent one-trial-per-domain semantics that the annotations only hint at.

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

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

Purpose and preconditions are front-loaded, and the error-code enumeration earns its place by telling the agent what to expect. It is dense and slightly run-on, but nearly 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?

An output schema exists, so return values need not be described, and the description covers preconditions, side effects (7-day TTL), failure modes, and the sibling escape hatch. Complete enough for a mutating onboarding call.

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% and the nested body/legal_entity semantics live in the schema, so the description only adds the attestation=true requirement and the note that ttl/expires_at are ignored (fields not even present in the schema). Useful, but it does not compensate for the undocumented authorization 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?

States a specific verb and resource ('Create a 7-day trial tenant') scoped to 'the caller's business email domain', and tags the use case (UC-052). It is clearly distinct from registration/invitation siblings, and it even names the alternative (start_inquiry) for the exhausted-trial case.

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

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

Preconditions are explicit ('verified email on a business domain and attestation: true'), and the trial.exists_for_domain branch routes the agent to start_inquiry. It lacks a general 'do not use this when X' beyond that one alternative, but the context is strong.

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 (destructive=true, idempotent=false), the description discloses real behavioral traits: a notification email is sent to the requester, the email names the tenant but never the dismissing admin, the requester may re-request, and the exact failure condition is 409 access_request.not_pending. That is meaningful side-effect and error semantics an agent cannot infer from the schema.

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

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

Four tight, front-loaded clauses: action first, then role requirement, then side effect, then failure mode. No filler and every clause carries distinct information.

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

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

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. The description adds preconditions, notification behavior, and the 409 case; the main remaining gap is how the `authorization` value is supplied/authenticated.

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%, so the description carries the load. It indirectly clarifies the authorization parameter (must be an admin/owner of the tenant) and ties access_request_id to a pending request, but it never names or fully explains either parameter, leaving the input contract partly implicit.

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 precise verb+resource — 'Dismiss a pending access request' — and immediately qualifies the acting role (admin/owner of the request's tenant). This clearly separates it from siblings like approve_access_request and withdraw_access_request, which are different actions on a different actor's behalf.

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 strong context for use: the caller must be admin or owner of the request's tenant, and the request must be pending (enforced by a 409 otherwise). It does not explicitly name or route to alternatives such as approve_access_request or withdraw_access_request, 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?

The annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false, but the description adds nothing beyond them. It does not explain that the operation reaches outside the system (openWorldHint) or clarify how a 'fetch and suggest' operation is non-read-only, and the output schema exists but the description still doesn't characterize the behavior.

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

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

A single compact sentence that front-loads the primary action. The trailing '(UC-057)' tag is dead weight but the overall size is appropriate.

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?

Although an output schema excuses the description from documenting return values, the definition still omits what 'domain imprint' contains, what the suggested legal-entity details are for, and any workflow context. For a non-read-only, open-world tool this is materially under-specified.

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

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

The single required 'authorization' parameter has 0% schema description coverage, and the description says nothing about its format (bearer token? header?). With coverage this low, the description is expected to compensate but 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?

The description pairs a verb ('Fetch') with a resource ('the caller's domain imprint') and adds a second action ('suggest legal-entity details'). However, 'domain imprint' is undefined jargon and the internal ticket reference '(UC-057)' adds no meaning, leaving an agent unsure what data is actually produced or how it differs from the related sibling get_legal_entity_types.

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, no prerequisites stated, and no alternatives named. The sibling list contains several plausibly overlapping tools (get_legal_entity_types, start_inquiry), yet the description gives no signal for choosing between them.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower — and the description still adds genuinely new context by disclosing the RBAC restriction and the exact failure signal ('only the owner and billing contacts may read it (`403 rbac.insufficient_level`)'). It does not discuss rate limits or pagination, but for a single-object read those are minor.

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

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

Two tight sentences, zero filler: the return contents come first and the permission/error note second. Every clause carries information 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?

An output schema exists, so return-shape documentation is not required, and the description nevertheless enumerates the key fields. Combined with the RBAC note and the read-only annotations, an agent has everything needed to call this correctly; only the tenant_id default behavior is left implicit.

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

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

Schema description coverage is 0% for two parameters, so the description must carry the load and does not. It never explains what 'authorization' expects or how 'tenant_id' behaves (empty default, whether it falls back to the caller's tenant) — the phrase 'the tenant's stored billing details' only loosely implies tenant scoping.

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

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

The description gives a specific verb and resource ('Return the tenant's stored billing details') and enumerates the exact fields returned (VAT id, invoice address, invoice email, PO reference). It implicitly separates itself from the sibling 'complete_billing' by framing itself as a completeness check, though it never names that sibling outright.

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?

'Call this to check whether billing is complete' states a clear use context rather than just describing the resource. It stops short of an explicit when-not-to-use or an alternative-tool pointer, so it is clear but not exhaustive.

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 fully covered structurally. The description adds only the 'enabled' filtering and name ordering as behavioral context; return format is handled by the output schema, so this is adequate but not rich.

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

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

Three sentences, front-loaded with the return value then usage then fallback. Nothing is redundant, though the final routing sentence could be trimmed slightly.

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

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

An output schema exists so return values need not be described, and annotations carry the safety profile. The description supplies the calling context an agent needs; the only real gap is the undocumented authorization parameter.

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 'authorization' parameter is undocumented in the schema. The description never mentions it or how to supply credentials, so it fails to compensate for the coverage gap.

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 ('Return the enabled ApplicationTemplate catalog') plus the sort order ('ordered by name'). The scope ('enabled') and the fallback to a named sibling make it distinguishable from the other ~30 tools without opening the schema.

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

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

Explicitly says when to use it ('discuss trial and template options with a prospect or customer before starting a trial') and provides a concrete alternative ('start_inquiry') for the case where it doesn't answer. It stops short of stating when NOT to call it, but the routing is clear.

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

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

Annotations already establish readOnly, idempotent, closed-world, non-destructive behavior, so the safety profile is covered. The description adds ordering (alphabetical) and the escalation route, but says nothing about result size, completeness, or what happens for an unknown country.

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

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

Two short sentences with the core behavior front-loaded and no wasted wording. The second sentence is generic escalation boilerplate rather than tool-specific detail, which slightly dilutes the value.

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

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

An output schema exists, so return values need not be described, and annotations carry the safety profile. The only real gap is the unexplained `authorization` parameter, which is minor for a simple read-only lookup.

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%: `country` is documented as ISO 3166-1 alpha-2 and the description reinforces that the lookup is per-country. The `authorization` parameter is undocumented in both schema and description, so the description does not compensate for the coverage gap.

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 ('Return the legal-entity types') plus scope ('available for *country*, ordered alphabetically'). No sibling tool in the list returns this data, so the differentiation is implicit rather than stated, but an agent can tell exactly what this produces.

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 (look up legal-entity types for a given country), and it names `start_inquiry` as an escalation path when the answer is insufficient. That fallback is not an alternative for the same task, and there is no explicit when/when-not guidance or prerequisite statement.

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 one non-obvious behavioral fact, that a pending invitation or access request can surface in the result, but says nothing about return shape, freshness, or scope of tenants returned.

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

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

Two front-loaded sentences with no filler. The core action is stated first, then the usage guidance, and every clause carries information the agent needs.

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

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

An output schema exists, so return values need not be explained, and the description covers purpose and invocation context well. The only real gap is the undocumented authorization parameter, which is the sole input.

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% for the single required 'authorization' parameter, and the description never mentions it. It does not state whether it is a bearer token, API key, or session identifier, so the description fails to compensate for the schema gap.

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 ('Return the caller's access level') plus the scoping unit ('per related tenant'), which is enough for an agent to distinguish it from sibling tools like list_members or get_billing without opening the schema.

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

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

Explicitly names the trigger conditions: check authorization before attempting a privileged action, or discover a pending invitation/access request. It gives clear when-to-use context but does not name an alternative tool or state when not to use it.

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

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

Annotations cover safety (readOnly, idempotent, non-destructive, closed-world). The description adds genuine behavioral context beyond them: it returns three distinct fields (status, result, error) and is designed for repeated polling until completion. It does not mention rate limits or retry cadence, so not 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?

Two tightly written sentences with the core purpose front-loaded and no filler. Every clause carries information (what is returned, where the id comes from, how to use 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?

An output schema exists, so return values need no elaboration, and annotations already carry the safety profile. For a simple two-param read tool the description is nearly sufficient, with the only gap being the unexplained `authorization` parameter.

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 0% for two required params, so the description carries the burden. It hints at operation_id's provenance (the `Location` of a `202` from `complete_billing`) but gives no format details, and `authorization` is never addressed. It only partially compensates for the coverage gap.

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: return status, result and error of an operation the caller started. It also anchors the resource to a concrete sibling (the `202`/`Location` from `complete_billing`), so an agent can place it precisely among the 30+ siblings.

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

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

Gives explicit usage context: 'Call this to poll it to completion,' which tells the agent this is the polling endpoint for previously started async work. It does not name when NOT to use it or any alternative tool, but none of the siblings serves the same polling 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds the useful fallback-escalation path but says nothing about rate limits, auth requirements, or what the returned step entails, so it only modestly exceeds the annotation bar.

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 primary purpose front-loaded before the fallback instruction. Every sentence earns its place.

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

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

An output schema exists, so return values need not be explained, and annotations cover safety. However, the description omits any mention of the authorization parameter and does not clarify what an 'onboarding step' represents, leaving meaningful gaps for a tool that gates an onboarding flow.

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% for the single 'authorization' parameter, so the schema provides no meaning. The description never mentions the parameter at all, leaving its format and expected value entirely undocumented; only the conventional name hints at its purpose.

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: 'Return the next onboarding step,' which is clear and distinct from sibling tools like get_my_access or get_my_operation. It also names a sibling (start_inquiry) as the fallback path, aiding differentiation, though it doesn't clarify scope (per-user vs per-tenant) of the onboarding route.

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

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

Provides an explicit alternative and the condition that selects it: 'If this doesn't answer your question, call start_inquiry... or request a call.' This is real routing guidance, but it only covers the failure case; there is no positive statement of when this tool should be preferred over the other get_* / start_* 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 carry the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), so the bar is lowered, but the description adds nothing beyond the purpose. It does not state what permissions are needed, whether re-granting is safe, or what happens on conflict.

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, which is structurally clean. But the terseness borders on under-specification for a mutation tool with four parameters and a nested object.

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

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

An output schema exists, so return values need not be explained, but for a non-idempotent mutation with 4 undocumented parameters and no annotations covering auth requirements, the definition is too thin to guide a correct call.

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% across 4 parameters, including a nested body object with three required fields. The description only loosely gestures at 'role' and 'scope' and leaves sub, tenant_id, and authorization entirely unexplained, so it fails to compensate for the coverage gap.

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 ('Grant') and resource ('role x scope assignment') plus the target ('tenant member'), so an agent can tell it is an authorization-granting tool. However, it never names revoke_assignment for differentiation, and the 'role x scope' phrasing is idiosyncratic.

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 context, no mention of prerequisites such as the required authorization token, and no reference to alternatives like revoke_assignment or create_access_request. The agent gets no routing help beyond the one-line purpose.

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 non-open-world behavior, so the safety profile is covered. The description adds real value beyond them by disclosing the authorization boundary that shapes the result set ('at least a viewer'), which an agent needs to interpret what comes back.

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

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

Three sentences, benefit and scope front-loaded, no filler. The trailing parenthetical is awkward enough to slightly weaken an otherwise 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?

An output schema exists, so return-value detail is not required here, and the description covers audience, scope and the one meaningful parameter conditional. Only the ambiguous tenant_id parenthetical keeps it from being fully self-sufficient at the point of call.

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%, so the description must carry parameter meaning. It does explain tenant_id's effect ('list one tenant's consents only'), but the clarifying parenthetical ('a caller of several tenants must') is grammatically incomplete and leaves the actual constraint ambiguous, and authorization is not addressed.

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 precise verb and resource and additionally defines the exact result scope: the caller's own consents plus tenant-scope consents for tenants where the caller is at least a viewer. That level of specificity clearly separates it from the write-side sibling record_consent.

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

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

It states a concrete usage trigger ('Call this to check which legal documents have already been accepted before asking again') and a conditional for the optional parameter. It stops short of naming the complementary alternative (record_consent) explicitly, but the context for when to invoke it is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description nevertheless adds meaningful behavioral context beyond them: result ordering and the security-relevant guarantee that the raw token is never included.

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

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

Two sentences, zero filler. The scope/ordering fact leads, with the usage hint and the token guarantee following — appropriately front-loaded for an agent scanning for a match.

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

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

An output schema exists, so return values need no explanation, and annotations cover the safety profile. The remaining gap is minor: no mention of pagination or status filtering, which an agent might reasonably expect from a list endpoint.

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% for two parameters, so the description must compensate. It implies the tenant scope ('caller's tenant'), which suggests how tenant_id behaves, but never explains tenant_id's default/empty-string semantics or the authorization parameter's role.

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 ('List all invitations'), scopes it to the caller's tenant, and specifies ordering ('most recent first'). The status enumeration (pending, accepted, revoked) makes clear this is a read-only overview, cleanly distinct from the create/revoke/accept siblings.

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

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

Gives a concrete usage context: 'Call this to show a tenant admin which invitations are pending, accepted, or revoked.' It does not name an alternative tool or state when not to use it (e.g., vs. list_members), so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds one semantic detail about the shape of the returned data (effective role x scope assignments), but says nothing about permissions needed or result size/pagination.

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 verb and resource come first and the qualifier follows. 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?

An output schema exists, so return values need not be explained, but with zero schema coverage on a required authorization parameter and no usage context, the definition is thin for a tool that gates access to membership data.

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% for two parameters, one of which (authorization) is required. The description never mentions tenant_id or authorization, so it does not compensate for the schema's silence on what these fields mean or how tenant scoping works.

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 ('List tenant members') plus a qualifier on the returned data ('effective role x scope assignments'). This separates it from siblings like list_invitations and list_consents, though it never names an alternative 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?

No when-to-use guidance, no prerequisites, no mention of when another listing tool is more appropriate. The agent must infer that this is the tenant-wide membership listing purely from the tool name and the word 'tenant' in the description.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds one useful behavioral detail — that only *active* subscriptions are returned — but says nothing about scoping when tenant_id is supplied or omitted. Adequate but thin against an otherwise rich annotation 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?

Two sentences, zero filler, with the purpose stated first and the usage cue second. Nothing could be removed without losing meaning.

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

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

For a read-only list tool with an output schema (so return values need no explanation) and only two parameters, the description covers enough to call it correctly. The remaining gaps — tenant_id override behavior and result limits/pagination — are minor.

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%, so the description carries the burden for both parameters. 'Caller's tenant's' implies tenant_id defaults to the caller's own tenant, which is useful, but neither the tenant_id override nor the authorization requirement is explained. Partial compensation 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?

'Return the caller's tenant's active service subscriptions' names a specific verb, resource, and scope, and the follow-up sentence implicitly separates it from the sibling add_tenant_service. An agent can tell what it returns and why 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?

'Call this before offering to add a service, to check what is already subscribed' gives explicit sequencing guidance and a concrete trigger condition. It stops short of naming the alternative tool or stating exclusions, but the when-to-use is unambiguous.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true and openWorldHint=false, so safety is covered. The description adds the one behavioral trait annotations cannot express: this mutation is a consent capture gated on prior user disclosure and affirmative confirmation. It stops short of explaining the required 'authorization' input or auth/permission requirements.

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

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

Two tight clauses with no filler, and the core action is front-loaded before the precondition. The semicolon-joined precondition reads slightly awkwardly but costs nothing in 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?

An output schema exists, so return values need no explanation, and the consent workflow gate is well covered. The remaining hole is the 0%-documented parameter set, making the definition adequate but incomplete for a tool with a required, unexplained 'authorization' input.

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% across four parameters, so the description carries the full burden and largely fails. 'Legal document version' loosely maps to document_version, but document_code, tenant_id and especially the required, opaque 'authorization' parameter are never explained.

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 ('Record acceptance of a legal document version') and even notes the effect ('return the entry'). This cleanly separates it from the read-side sibling list_consents and from other write tools like accept_invitation or approve_access_request.

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

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

Provides an explicit sequencing precondition: call only after showing the user the document URL and version and getting an explicit affirmative answer. That is strong usage guidance, but it names no alternative (e.g., list_consents for reading prior consents) and offers no negative case beyond the consent gate.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is fully covered elsewhere. The description adds nothing beyond it: it does not say whether the revocation is reversible, whether it applies to all matching role/scope pairs, 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?

A single tight sentence with no filler, which is structurally sound. However, that brevity comes at the cost of under-specification rather than true economy.

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 destructive, permission-sensitive mutation with no output schema and no parameter documentation, so the description needs to do more work. It omits the authorization requirements, the effect on the target member, and any confirmation or irreversibility note.

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% across four parameters, so the description carries the full burden and largely fails. 'Role x scope assignment' hints at what 'id' identifies and 'tenant member' hints at 'sub', but 'authorization' and the tenant_id default are entirely unexplained, leaving two of four parameters undocumented anywhere.

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

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

Specific verb (revoke) plus a precisely-scoped resource (a role x scope assignment) and target (a tenant member), so an agent can distinguish it from revoke_invitation and withdraw_access_request. It does not explicitly name its inverse sibling grant_assignment, so it falls short of full sibling routing.

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 or when-not-to-use guidance, no prerequisite (e.g., that the assignment must exist), and no reference to the alternative grant_assignment for the reverse operation. Usage is only inferable 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds real context beyond that: the operation only applies to pending invitations and invalidates the acceptance token. It omits auth requirements and what happens to already-accepted invites' records, so not 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?

Two sentences, front-loaded with the action and effect, then the usage condition. No filler or redundancy; 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?

Purpose, trigger, and state constraint are present and no output schema needs explaining, but for a three-parameter mutation tool with zero schema documentation the description says nothing about the parameters or authorization context. Adequate for intent, incomplete for invocation.

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

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

Schema description coverage is 0%, so the description carries the full parameter burden, yet it only alludes to an 'invitation' and 'token' without explaining invitation_id, tenant_id, or the required authorization value. It adds essentially nothing about the three parameters the agent must supply.

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 (revoke) and resource (a pending invitation) plus the concrete effect: the token can no longer be accepted. The 'pending' qualifier and 'accepted invitations cannot be revoked' clause separate it cleanly from accept_invitation, create_invitation, and list_invitations.

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

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

Gives an explicit when-to-use ('withdraw an invite sent by mistake or no longer needed') and a when-not ('accepted invitations cannot be revoked'). It never names the competing sibling tools directly, so the routing is implied rather than spelled out, keeping it short of a 5.

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

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

Goes well beyond the annotations: discloses that a 6-digit code is emailed, that no account exists yet, that free-mail domains are refused, and that the response is indistinguishable whether or not the address is already registered (enumeration protection). None of this is derivable from 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?

Front-loaded with the action and key parameters, then the flow and constraints. Dense but every sentence carries information; only slight tightening possible across the multi-clause sentences.

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

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

An output schema exists, so return values need no explanation; the description still supplies the crucial challenge_id/code handoff and the free-mail guard. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 50% and a nested body wrapper exists. The description names email/name as inputs and marks company as optional, partially compensating, but adds no format rules for the email or guidance on the `body`/`authorization` wrapper fields.

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

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

States a specific verb+resource ('start registering a 4chems account') with the exact identifying fields (email, name, company) and names the follow-up tool verify_account_registration. Clearly separable from start_registration, start_inquiry, and start_device_login.

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

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

Explicit when-to-use (business email, anonymous, no account yet) and when-not (free-mail refused), with the alternative route named ('use the company address, or call start_inquiry'). The end-to-end sequence (start -> ask user for code -> verify) is 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) by disclosing that the call is anonymous, that it initiates an interactive human step, and critically that the response never exposes the Keycloak device_code or the agent client secret. That security-relevant non-disclosure is exactly the context annotations cannot carry.

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

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

A single dense paragraph that is front-loaded with the operation, then prerequisites, then the human-in-the-loop handoff and polling loop. Every clause adds actionable information; nothing is decorative.

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

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

An output schema exists, so return-value detail is correctly omitted, yet the description still tells the agent which response fields to surface to the human and which to expect on the follow-up call. The full interactive flow is covered.

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 0% and the single 'authorization' parameter with default "" is never named or explained. The description does characterize the call as 'Anonymous, empty body', which implies the auth parameter is unused, but that inference is left to the agent rather than stated.

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 ('Sign in to an existing account by device login') and anchors it to a named standard (RFC 8628), which immediately separates it from siblings like start_account_registration and verify_device_login. An agent can tell exactly what this does without opening the schema.

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

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

Gives explicit prerequisites ('the account must exist... start_account_registration, then set the password through the emailed link'), names the follow-up tool (verify_device_login with challenge_id), and specifies the polling cadence ('waiting interval seconds between calls'). Both when-to-use and how-to-proceed are 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 only cover safety flags (readOnly=false, idempotent=false, destructive=false, openWorld=false). The description adds real behavioral context beyond that: the draft is stored anonymously, a 6-digit code is emailed, and the inquiry is not delivered to 4chems until verification succeeds. It omits whether repeated calls resend codes or how long the challenge_id stays valid.

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

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

Three short sentences, front-loaded with the action and followed by the required follow-up. No filler, and every sentence carries information the agent needs to complete the task.

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?

Output schema exists so return values need not be explained, and the description supplies the challenge_id handoff. However, for a nested-object mutation with 0% schema description coverage and an undocumented 'authorization' parameter, the description is not complete enough to tell an agent what to send.

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 input is a nested body object with six fields (name, email, topic, message, company, website) plus an opaque 'authorization' string. The description says nothing about any of these fields, so it fails to compensate for the coverage gap and leaves the required content of the payload undefined.

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

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

States a specific verb and resource ('Store an anonymous inquiry draft and email a 6-digit verification code') and explicitly contrasts itself with the sibling verify_inquiry, which completes the flow. An agent can separate this tool from the other start_*/create_* onboarding siblings without opening a schema.

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

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

Gives a clear operational sequence: ask the user for the emailed code, then call verify_inquiry with the returned challenge_id and code. It does not state when not to use it or how it relates to siblings like create_access_request, but the context and next step are unambiguous.

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

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

The annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description adds genuine non-annotation context — deprecation status and behavioural equivalence to start_device_login — but says nothing about the authorization parameter, auth requirements, or failure 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 deprecation warning is correctly front-loaded, but the sentence 'use start_device_login. Deprecated — use start_device_login (same behaviour)' restates the same instruction twice across the description and title, which is wasted space rather than 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?

An output schema exists so return values need not be described, and the essential routing decision (don't use this, use start_device_login) is present. However, the undocumented authorization parameter and the absence of any statement on whether the tool still works leave gaps for an agent deciding to invoke 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 0% and the single parameter 'authorization' is entirely undocumented in both schema and description. With one unexplained parameter the description should compensate, and it 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?

The description never states what the tool actually does — it only declares deprecation and points at a replacement. The phrase 'same behaviour' implicitly ties it to start_device_login, but a sibling named start_account_registration is left unaddressed, so the agent gets routing information without a clear statement of the resource/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?

'DEPRECATED: use start_device_login' is an explicit when-not-use directive with a named alternative, which is exactly the guidance an agent needs. It falls short of 5 because it doesn't say whether the tool still functions or when a legacy caller might legitimately need 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?

The annotations only cover the safety quadrant (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false); the description adds the account-creation side effect, the one-shot retry prohibition, and a credential-handling warning about never soliciting a password. These are meaningful behavioral disclosures beyond the structured hints, though error/failure behavior is still unstated.

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 and its side effect front-loaded, followed by the guardrails. The parenthetical '(`challenge_id`, `code`)' squeezed onto 'the emailed 6-digit code' is slightly awkward and could be misread as both parameters being the same emailed value.

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

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

An output schema exists, so return values need no prose; the annotations cover the safety profile and the description covers the mutation side effect, the one-shot constraint, and the credential warning. For a two-parameter verification call, an agent has what it needs to invoke it correctly.

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

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

Schema coverage is 50%: `code` and `challenge_id` carry only type/format constraints and the `authorization` parameter is undocumented. The description clarifies that the code is an emailed 6-digit value tied to the pair (`challenge_id`, `code`), which is useful, but it says nothing about the authorization parameter or which value came from which prior step.

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 (verify the emailed 6-digit code) plus the concrete side effect (create the 4chems account), so the agent knows this is the account-registration completion step. It does not explicitly differentiate itself from the similar siblings verify_registration, verify_device_login, and verify_inquiry, so it falls short of a 5.

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

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

The description gives real operating constraints (never guess or retry codes, never ask for a password), which implies this runs once after the user receives the emailed code. However it never states when to prefer this over verify_registration or the other verify_* siblings, nor what to do if the challenge is missing or expired, leaving routing 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 only give a blunt safety profile (not readOnly, not idempotent, not destructive); the description goes well beyond them by disclosing the two-state machine (pending vs approved), the retry_after backoff contract, the once-only token issuance, and the anonymous/no-auth precondition. This is exactly the behavioral context an agent needs to drive a device flow correctly.

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 dense sentences, front-loaded with the purpose, the pending-state contract, and the terminal-state contract in order of use. No filler; the embedded JSON example earns its space by pinning the response shape.

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?

Strong overall coverage for a stateful polling tool, and it even describes the pending and success payloads despite an output schema existing. It omits failure terminals (challenge denied or expired), which matter in a device-login flow, leaving a small completeness 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 coverage is only 50% — challenge_id and authorization carry no descriptions — but the prose compensates by specifying that the same challenge_id must be reused across polls and that authorization takes the 'Bearer <token>' form. It adds real meaning over the bare schema, though it never explains where challenge_id originates.

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 ('poll a device login to token issuance') plus scope markers (UC-091, RFC 8628), making it immediately distinguishable from the sibling start_device_login. An agent knows exactly what this endpoint accomplishes without opening the schema.

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

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

Explicitly describes the polling loop: while pending, wait retry_after seconds and re-call with the same challenge_id, and on approval pass access_token to every other tool. It lacks an explicit statement that start_device_login must precede it or what to do on denial/expiry, but the operative usage conditions are unusually clear.

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

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

Annotations already declare it is a non-read-only, non-destructive, non-idempotent, closed-world operation, so the safety bar is lower. The description usefully adds the delivery-to-helpdesk side effect, but omits auth requirements (the authorization parameter), what happens on an invalid code, and whether re-verification is safe.

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, with the core action stated first. It is arguably too terse for a two-part nested input, but it is not padded.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. However, the workflow prerequisite (getting challenge_id from start_inquiry) and the authorization requirement are absent, leaving the agent without enough to invoke the tool correctly in sequence.

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%, so the description carries the full burden. It clarifies that code is 6 digits, matching the min/maxLength constraint, but says nothing about challenge_id (a UUID tying to the start_inquiry challenge) or the authorization parameter, leaving half the input unexplained.

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

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

The description gives a specific verb (verify) plus the resource (the 6-digit code / the inquiry) and adds a concrete effect (delivering to the helpdesk inbox). It is clearly distinguishable from start_inquiry, though it does not name that sibling explicitly to disambiguate a paired start/verify flow.

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 use this versus the many verify_* siblings (verify_registration, verify_device_login, verify_account_registration) or start_inquiry. The prerequisite that a challenge_id must first come from start_inquiry 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description needn't restate it. Beyond the deprecation marker, 'same behaviour' is too vague to be useful, and nothing is said about the authorization requirement or which challenge is consumed.

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 duplicated almost verbatim: 'DEPRECATED: use verify_device_login' followed by 'Deprecated — use verify_device_login (same behaviour).' Half the text is redundant repetition.

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

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

An output schema exists and the deprecation is surfaced, which covers the essentials for a deprecated alias. However, the auth parameter and the nature of the registration challenge being verified are left 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?

Schema coverage is only 50% — the nested 'body.challenge_id' is documented in-schema, but the 'authorization' parameter is undocumented everywhere. The description adds no parameter meaning whatsoever, so it fails to compensate for the gap.

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 never states what the tool actually does; the only functional clue is the vague assertion that it has 'same behaviour' as verify_device_login. It does redirect the agent to the correct sibling, but it restates the name/title rather than defining the 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?

It explicitly names the replacement tool (verify_device_login), which is the key routing decision for an agent. It stops short of stating outright that this tool should never be called for new work or what happens if it is called.

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, it discloses a real side-effect ('no notification is sent') and precise error semantics: 404 access_request.not_found is deliberately indistinguishable from an unknown id, and 409 access_request.not_pending applies unless pending. This is exactly the kind of behavioral detail annotations cannot carry, and it is consistent with destructiveHint=true and idempotentHint=false.

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 dense sentences, zero filler; the core action and its scope come first, followed by the failure contract. 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?

For a guarded mutation, the description covers scope, side-effect, and error behavior, and an output schema exists so return values need not be restated. An agent has everything needed to call it correctly or avoid 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 0% for both parameters, so the description carries the burden. It never explains the 'authorization' parameter, but 'the caller's own' does constrain what access_request_id must refer to (a pending request owned by the authenticated caller), which is meaningful semantics. Partial compensation 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 ('Withdraw') and resource ('access request') plus a scope qualifier ('the caller's own pending'). This cleanly separates it from sibling mutations such as approve_access_request, dismiss_access_request, and create_access_request without needing their schemas.

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 defines the calling context precisely: only the caller's own pending request can be withdrawn, with explicit failure modes (404 for other callers/unknown ids, 409 when not pending). It stops short of naming alternatives (e.g., dismiss vs. approve), so the agent must infer the routing decision.

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