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

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing: not that this is a mutating create, not whether it requires an app relationship or specific role, not whether it fails on duplicates, and not what it returns. The only behavioral hint (POST) is already implied by the name and path.

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

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

It is short, but the brevity reflects under-specification rather than economy: the endpoint path is duplicated needlessly in parentheses and no informational content is added. There is nothing to reward beyond the fact that it is a single sentence.

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

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

For a create endpoint with a required nested JSON:API body, no output schema, and no annotations, the description supplies none of the information an agent needs to call it correctly. Referring to an external OpenAPI component does not fill 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 nominally 100%, so a baseline of 3 would apply, but the description merely repeats the schema's own text ('see OpenAPI components.schemas.AccessibilityDeclarationCreateRequest') and points to an out-of-band document that is not resolvable inside this definition. The single required nested body parameter has additionalProperties {} with no inlined field semantics, so the agent still cannot know what to put in the envelope.

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 the HTTP verb and resource path (POST /v1/accessibilityDeclarations), which does convey 'create an accessibility declaration', but it is essentially a restatement of the tool name/endpoint with the path repeated verbatim inside parentheses and no human-readable statement of purpose. It does nothing to distinguish this tool from its siblings accessibility_declarations_get_instance, accessibility_declarations_update_instance, and accessibility_declarations_delete_instance.

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

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

There is no guidance at all on when to use this tool versus the sibling get/update/delete instance operations, nor any mention of prerequisites such as which app or version the declaration must be attached to. The agent is left to infer everything from the tool name.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing: not that the operation is destructive and likely irreversible, not whether dependent resources are affected, not auth requirements. A raw endpoint string is insufficient for a delete tool.

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

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

The text is short but the entire content is duplicated verbatim in parentheses, adding zero information. Brevity here is under-specification rather than conciseness, since nothing useful is front-loaded.

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

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

For a destructive delete operation with no annotations, no output schema, and a trivial description, the definition leaves out everything an agent would need: consequences, preconditions, error behavior, and confirmation semantics. It is not adequate to invoke safely.

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

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

Only one parameter (id) with 100% schema description coverage, so the schema already documents it fully. The path template '{id}' in the description merely mirrors the parameter without adding format, source, or constraint details, so the baseline 3 applies.

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

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

The description states a concrete HTTP verb and resource path (DELETE /v1/accessibilityDeclarations/{id}), so an agent can infer it deletes an accessibility declaration by id. However, it is essentially the tool name rendered as an endpoint, with no prose about what a declaration is and no differentiation from siblings like accessibility_declarations_update_instance.

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

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

There is no guidance whatsoever on when to use this tool versus the sibling create/get/update variants, nor any precondition such as required permissions or irreversibility. An agent learns nothing beyond the HTTP method.

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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing beyond the HTTP verb: no auth/permission requirements, no statement of what is returned, no note about behavior for a missing or invalid id. A raw path echo is not behavioral disclosure.

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

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

It is short and front-loaded, but the parenthetical repeats the identical route with zero added information, so one of the two units of text is pure noise. Brevity here reflects thin content rather than disciplined editing.

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

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

For a single-resource retrieval tool with no annotations and no output schema, the description should at minimum convey the concept of the returned object and auth expectations. The route does imply 'fetch the accessibilityDeclaration with this id', but nothing else needed to call it correctly is present.

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

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

Schema description coverage is 100% (both 'id' and 'fields_accessibilityDeclarations' are documented in the schema, including the full field enum), so the baseline of 3 applies. The description adds nothing about the path parameter or sparse-fieldset syntax, but it also does not mislead.

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

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

The description is only the raw HTTP route, echoed twice: 'GET /v1/accessibilityDeclarations/{id} (GET /v1/accessibilityDeclarations/{id})'. It restates the tool name (accessibility_declarations_get_instance) in URL form rather than stating a purpose in prose; an agent learns only that this fetches one accessibility declaration by id, and gets no differentiation from the many sibling *_get_instance tools.

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

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

There is no when-to-use, when-not-to-use, or alternative routing. Siblings such as accessibility_declarations_create_instance, _update_instance, _delete_instance, and apps_accessibility_declarations_get_to_many_related are never referenced, so the agent must infer selection from the name alone.

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

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

No annotations are provided, so the description carries the full burden. It discloses nothing about authorization requirements, whether the update is partial or full, what happens to fields not supplied, or any side effects. The only implicit behavioral hint is the PATCH verb, which signals a partial update, but that is not stated and is already implied by the route.

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

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

It is short and front-loaded, which is good, but the parenthetical '(PATCH /v1/accessibilityDeclarations/{id})' duplicates the text immediately preceding it and earns no place. The remaining content is a single useful pointer to the body schema.

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

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

For a mutation tool with no annotations, no output schema, and a nested JSON:API envelope body, the description is not complete enough: it does not enumerate updatable fields, note auth/permission needs, or explain the envelope structure beyond a schema name the agent cannot resolve. An agent has little to act on beyond the required parameters.

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

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

Schema description coverage is 100% and both parameters (id, body) are documented in the schema. The description merely references components.schemas.AccessibilityDeclarationUpdateRequest, which the schema description already points to, so it adds essentially no new meaning. Baseline 3 for full schema coverage applies.

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

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

The description is essentially the operation ID restated as an HTTP route: 'PATCH /v1/accessibilityDeclarations/{id}'. It never says in plain language that it updates an existing accessibility declaration, and it does nothing to differentiate itself from its four siblings (accessibility_declarations_create_instance, get_instance, delete_instance). It is marginally more than the name because it names the HTTP verb, but that is decodable from the name itself.

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

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

There is no guidance on when to call this versus create_instance, get_instance, or delete_instance, nor any prerequisite or ordering information. The rubric assigns 2 for 'no guidance,' and the description contains none.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose one genuinely useful trait — the .p8 file is not read into the MCP, only its path is stored — which is security-relevant. It omits what happens on duplicate names, whether the new account becomes active, and what permissions are needed.

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

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

Three short sentences with zero waste; the core action is front-loaded and the clarifying disk-path note follows immediately. Nothing is repeated or 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?

For a credential-registering mutation with no annotations and no output schema, the description covers the essential inputs and one important side effect. It is still silent on post-conditions (is the account activated?), duplicate handling, and error behavior, leaving gaps an agent may need.

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

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

Schema description coverage is 67%, so most parameters are already documented in the schema. The description reinforces keyId, issuerId and keyFile but adds no format or constraint detail beyond the schema, and never mentions the name, scope, or description parameters.

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

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

States a specific verb and resource — 'Register a new App Store Connect account' — which is clearly distinct from the read/switch/remove account siblings. It does not explicitly name or contrast with those siblings (accounts_switch, accounts_update), 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 tells the agent what to pass but never when to use this tool versus accounts_switch or accounts_update, nor does it state prerequisites such as generating the API key in App Store Connect first. 'Provide the Key ID...' is input instruction, not usage guidance.

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

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

With no annotations, the description carries the full burden and does add real behavioral context: the active account governs credentials for all later calls, and pinning via ASC_ACCOUNT makes the account non-switchable. It does not describe the return format (e.g., what fields identify the account), but for a simple read this is a solid disclosure.

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

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

Three short sentences, front-loaded with the core purpose, then the credential effect and the pinning constraint. No filler; 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?

For a zero-param, read-only status tool with no output schema, the description covers purpose and the key operational constraint. It stops short of describing what the response contains beyond the hinted `pinnedTo`, which is a minor gap given no output schema exists.

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

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

The tool takes no parameters, so the baseline is 4. The description's mention of `pinnedTo` describes a returned/derived value rather than an input, which slightly enriches understanding without being required.

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 ('Show which account is currently active') that is unambiguous and distinguishable from siblings like accounts_list (all accounts) and accounts_switch (change active account). An agent can tell it apart 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?

It clarifies the consequence of the current account ('All subsequent API calls use this account's credentials') and the pinning constraint, which is useful context. However, it never explicitly routes the agent to accounts_switch for changing the account, so usage is implied rather than stated.

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

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

With no annotations provided, the description carries the full burden and does well: it enumerates the returned fields and makes a security-relevant disclosure that key material is never returned. It does not mention auth requirements or whether the read is local-only, which are minor gaps for a zero-arg list.

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

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

Two sentences, no filler, and the most important constraint (never returns key material) is placed last as a clear boundary. 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?

There is no output schema, but the description compensates by naming the returned fields, so an agent knows what it will get. Only auth/prerequisite context is absent, which is a minor omission for a local list operation.

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

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

The tool takes zero parameters, so there is nothing for the schema to document and the baseline is 4. The description does not need to explain parameter syntax and correctly does not attempt to.

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 (List) and resource (App Store Connect accounts registered locally) with a clear scope ('every account'). It is distinguishable from siblings like accounts_current by the 'every' scope, though it never names those siblings explicitly.

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

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

The description implies when the tool is useful (inspecting locally registered accounts) but gives no explicit when-to-use guidance and never routes the agent to alternatives such as accounts_current or accounts_switch. Usage is left 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?

With no annotations, the description carries the full burden. It does disclose one genuinely useful behavioral trait: the .p8 credential file on disk is preserved, bounding the blast radius of a destructive-sounding operation. However, it says nothing about reversibility, whether removal is refused for the active account, or any side effects, so the destructive profile remains only half-specified.

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, the core action front-loaded and the important caveat immediately after. No filler, no restatement of the tool name.

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

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

For a one-parameter local-registry tool with no output schema, the description covers the action and the key non-effect on disk. It still leaves gaps an agent would want: identifier format and any precondition about the currently active account.

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 'name' parameter has 0% schema description coverage, and the description never states what form that name takes (account label, email, team ID) or how it matches a registry entry. The text implies an account is identified but adds no meaning beyond the bare schema.

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

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

The description gives a specific verb+resource ('Remove an account') scoped to 'the local registry', and the .p8 caveat sharpens that scope. It is clearly distinguishable from accounts_add/accounts_switch/accounts_list without opening a schema, though it never names a sibling 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?

There is no guidance on when to remove an account versus switching away from it or updating it, and no prerequisites (e.g., whether the account must be inactive). The 'local registry' phrasing implies the domain but does not route the agent among the accounts_* 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?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states the action (mutates state) but does not mention authentication needs, side effects, error conditions, or what the response returns.

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

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

The description is a single sentence with no unnecessary words. It is to the point but very brief, which is acceptable for a simple tool.

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

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

For a tool with one parameter, no output schema, and no annotations, the description covers the essential purpose but lacks context about what 'active' means, expected results, and error handling. It is adequate but not thorough.

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

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

The single parameter 'name' has no description in the JSON schema (0% coverage), and the tool description adds no extra meaning beyond the parameter name. The parameter is self-explanatory as an account name, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: switching the active account to an existing one. It distinguishes itself from sibling tools like accounts_add, accounts_remove, and accounts_current.

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

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

The description implies usage when multiple accounts exist and you need to change the active one, but it does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention prerequisites like listing accounts first.

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

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

With no annotations, the description carries the full behavioral burden. It says 'Change' (mutation) but never states auth/permission requirements, whether changes are reversible, or how the account is selected. It also leaves ambiguous whether the required 'name' parameter is the account identifier or a field being changed.

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

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

Two short, front-loaded sentences with no filler; the purpose leads and the partial-update hint follows. Brevity here reflects under-specification rather than padding, so it earns credit for structure but not a 5.

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

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

For a mutation tool with no annotations, no output schema, and 6 undocumented parameters at 0% coverage, the description is far too thin. An agent cannot confidently identify the target account or predict the effect of the update from this text alone.

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

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

Schema description coverage is 0% across 6 parameters, so the description must compensate and does not. It only implies partial-update semantics and says nothing about keyId, scope, keyFile, issuerId, description, or whether 'name' identifies the account rather than being updated.

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 clear verb+resource ('Change ... fields of an existing account'), which is unambiguous against the sibling list of account tools (accounts_list, accounts_add, accounts_remove, accounts_switch). It does not explicitly differentiate itself from those siblings, 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?

'Provide only the fields you want to update' gives useful partial-update semantics, so the agent knows omitted fields are untouched. However there is no guidance on when to use this versus accounts_add/accounts_switch, no prerequisites, and no mention of how the target account is identified.

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?

No annotations are provided, so the description carries the entire behavioral burden, and it discloses nothing: not pagination behavior, not default page size, not auth requirements, not what the response contains. A bare endpoint string is the minimum possible disclosure.

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

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

It is short, but the brevity is under-specification rather than conciseness — the same URL is even duplicated in parentheses. Nothing here is front-loaded because there is nothing of substance to front-load.

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

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

For a collection endpoint with three optional query parameters, no annotations, and no output schema, the description should at least state that it returns a paginated list of actor resources. It supplies none of that, leaving the agent to infer the entire behavior from the name.

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

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

Schema description coverage is 100%, so limit, filter_id, and fields_actors are already documented in the schema with their meanings. The description adds no parameter context, but the baseline of 3 applies when the schema does the heavy lifting.

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

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

The description is just the raw endpoint "GET /v1/actors (GET /v1/actors)", which restates the tool name (actors_get_collection) in URL form rather than describing what the tool does. It conveys no verb-resource semantics beyond what the name already implies and does nothing to distinguish it from siblings like actors_get_instance.

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, when-not-to-use, or alternative guidance at all. An agent has no signal about when to list actors versus fetching a single actor via actors_get_instance, or how this relates to filters such as filter_id.

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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing. It does not state that the call is read-only, whether the response is cached, what happens on an unknown id (404), or any auth/rate-limit 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?

It is short, but it is under-specified rather than concise, and the parenthetical repeat of the same path is pure redundancy. There is no front-loaded statement of purpose to front-load anything against.

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

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

For a simple read-instance tool with a complete input schema and no output schema, the description still omits the basic framing an agent needs: what resource is being fetched and what the response contains. With no annotations and no output schema, the description should at minimum state the read semantics, which it does not.

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

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

Schema description coverage is 100% and both parameters (id, fields_actors) are documented in the schema itself, so the baseline is 3. The description adds no syntax, format, or semantic detail about the id or the fields_actors sparse-fieldset selector beyond what the schema already says.

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

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

The description is nothing but the HTTP method and path, 'GET /v1/actors/{id}', repeated twice. It restates what the tool name already encodes (actors_get_instance) without stating in natural language what an actor is or what retrieving one yields. An agent gains no distinguishing information versus the sibling actors_get_collection.

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 whatsoever. The description does not say when to fetch a single actor versus listing the collection (actors_get_collection), nor does it mention prerequisites such as authentication or a known actor id.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses only that this is a PATCH (implying a partial mutation) and points at an external schema; it says nothing about required permissions, whether the change is reversible, what happens to unspecified fields, or any side effects of mutating an age rating declaration.

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 duplicates the exact same endpoint string 'PATCH /v1/ageRatingDeclarations/{id}' in parentheses, which is pure waste. It is short but structurally flawed because roughly half its content is redundant rather than additive.

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

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

For a mutation tool with no annotations and no output schema, the description is inadequate: it never explains what the update accomplishes, which fields are modifiable, or what the caller should expect. It offloads everything to an external OpenAPI document an agent may not have access to, leaving the tool underspecified.

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

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

Schema description coverage is 100% and both parameters (id, body) are documented in the schema. The description only repeats the schema's body reference to components.schemas.AgeRatingDeclarationUpdateRequest, adding no new meaning; per the high-coverage baseline, 3 is appropriate.

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

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

The description conveys a verb/action (PATCH) and the target resource (ageRatingDeclarations/{id}), so an agent can infer this updates one age rating declaration. However, it is phrased as a bare HTTP endpoint rather than a purpose statement, and it does nothing to distinguish itself from the many sibling update_instance tools or the age-rating relationship tools (e.g. app_infos_age_rating_declaration_get_to_one_relationship).

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. The agent is not told when this update should be preferred over sibling tools that also touch age rating declarations or app info. Only the mechanical HTTP method is provided.

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

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

With no annotations, the description carries the full behavioral burden, yet it discloses nothing: no auth/permission requirements, no idempotency or side-effect notes, no response behavior. It only restates the HTTP route and points to an external schema name.

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

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

Short, but the route is duplicated verbatim ('POST /v1/alternativeDistributionDomains (POST /v1/alternativeDistributionDomains)'), which is pure waste, and the schema reference duplicates the schema's own description. Front-loading is fine but the content is not earning its place.

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

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

For a create tool with a single nested-object body, no output schema, and no annotations, the description should explain the request envelope's key fields or at least what a successful creation yields. Pointing at an OpenAPI component name the agent may not be able to resolve leaves the definition substantially incomplete.

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

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

There is a single 'body' parameter and schema description coverage is 100%, so the schema already documents it as a JSON body referencing components.schemas.AlternativeDistributionDomainCreateRequest. The description merely repeats that pointer, adding no field-level meaning, which matches the baseline 3 for high schema coverage.

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

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

The description conveys a create operation on the alternativeDistributionDomains resource only through the REST route 'POST /v1/alternativeDistributionDomains'. There is no plain-language statement of what an alternative distribution domain is or what creating one accomplishes, though the resource and verb are technically identifiable.

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

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

No guidance on when to use this tool versus siblings such as alternative_distribution_domains_get_instance, get_collection, or delete_instance. No prerequisites, no context, and no exclusions are stated.

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

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

No annotations are provided, so the description must carry the behavioral burden. It reveals that the operation is a DELETE, but says nothing about required permissions, whether deletion is reversible, what associated data is removed, or rate limits.

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

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

The description is short but duplicates the same endpoint string in parentheses, which adds no information. It is not front-loaded with useful context, just a raw HTTP route.

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

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

For a destructive delete operation with no annotations and no output schema, the description is insufficient. It does not explain prerequisites, consequences, or what happens to references after deletion.

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

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

The schema fully documents the single required id parameter, so the baseline is 3. The description adds no meaningful semantics beyond repeating the id placeholder from the path.

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 restates the endpoint path and HTTP method already implied by the tool name, without explaining what an alternative distribution domain is or what deleting it entails. It is a tautology rather than a meaningful statement of purpose.

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

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

There is no guidance on when to use this tool versus alternatives, no preconditions, and no warning about destructive effects. The description only gives the HTTP route.

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?

No annotations are provided, so the description carries the full behavioral burden, and it discharges almost none of it. The embedded "GET" verb weakly implies a read-only, non-destructive operation, but there is no mention of pagination behavior (despite a limit parameter), authentication requirements, or the shape of the returned collection.

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 line is short but wastes its only content on restating the same path twice, which is pure redundancy rather than concision. It is under-specified rather than appropriately sized, leaving almost no useful signal.

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

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

For a list-collection endpoint with no output schema and no annotations, the description should convey scope (all domains, not one), pagination, and the read-only nature. None of that is present, so an agent must rely entirely on the schema and sibling naming to call it correctly.

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

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

Schema description coverage is 100%: both the limit and fields_alternativeDistributionDomains parameters are documented in the schema itself. The description adds no parameter detail whatsoever, so the baseline of 3 applies.

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

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

The description is just the HTTP path repeated twice in parentheses: "GET /v1/alternativeDistributionDomains (GET /v1/alternativeDistributionDomains)". It restates the tool name rather than stating in plain language that it lists/retrieves all alternative distribution domains. An agent can infer the resource from the path, but this is tautological rather than a clear purpose statement.

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

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

There is no guidance on when to use this collection endpoint versus the sibling alternative_distribution_domains_get_instance, alternative_distribution_domains_create_instance, or alternative_distribution_domains_delete_instance. No prerequisites, no scope, no alternatives are named.

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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing: no auth/permission requirements, no error behavior for a missing id, no note that this is a read-only fetch. The parenthetical merely duplicates the path.

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

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

It is short, but the parenthetical is pure duplication rather than conciseness — the same string is stated twice with zero additional information, so the content is under-specified rather than efficient.

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

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

With no annotations, no output schema, and a bare endpoint string, the definition omits everything an agent needs to call it confidently: return shape, id format, failure modes, and any scoping constraints.

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

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

Schema description coverage is 100%, with both id and fields_alternativeDistributionDomains documented in the schema, so the baseline is 3. The description adds nothing beyond the schema but is not misleading.

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

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

The description is the raw REST path repeated verbatim in parentheses, which restates the tool name rather than explaining purpose in plain language. An agent can infer 'fetch one alternative distribution domain by id' from the path and the sibling alternative_distribution_domains_get_collection, but the definition itself contributes no explanatory content.

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

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

No guidance on when to use this tool versus the collection sibling or any other retrieval tool. Nothing about prerequisites, id sourcing, or when-not-to-use is present.

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?

No annotations are provided, so the description carries the full behavioral burden and largely fails it: no mention of authentication scopes, rate limits, idempotency, side effects, or what the response contains. The one piece of real information is that the payload follows a JSON:API envelope defined by AlternativeDistributionKeyCreateRequest, which is a useful but minimal disclosure.

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

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

It is short, but the content is duplicated verbatim: the path 'POST /v1/alternativeDistributionKeys' appears twice, with the second occurrence in parentheses adding nothing. That is waste in an already sparse description.

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 mutation tool with no annotations, no output schema, and a nested body whose shape is deferred to an external OpenAPI component the agent may not have. Critical invocation information (required fields, envelope structure, auth requirements) is effectively out of reach.

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

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

There is a single 'body' parameter with 100% schema description coverage, so the schema already documents it. The description repeats the same pointer ('see OpenAPI components.schemas.AlternativeDistributionKeyCreateRequest') without adding field-level semantics, which is the expected baseline 3 when the schema does the heavy lifting.

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

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

The description restates the tool name as an HTTP route ('POST /v1/alternativeDistributionKeys') rather than stating what the tool accomplishes. An agent can infer creation from the name and the POST verb, but the text itself adds no purpose statement and does nothing to distinguish it from sibling tools like alternative_distribution_keys_get_instance or alternative_distribution_keys_delete_instance.

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, when-not-to-use, prerequisite, or alternative-tool guidance of any kind. The only signal is the POST path, which comes from the name rather than the description text.

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?

No annotations are provided, so the description carries the full behavioral burden, yet it discloses nothing: not whether deletion is permanent, whether dependent resources (e.g., domains, apps referencing the key) are affected, what permissions are required, or what the response is. For a destructive operation this is a serious gap.

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

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

It is short, but it is not efficient: the parenthetical duplicates the endpoint verbatim, so half the text is pure repetition. There is no front-loaded statement of intent, just a raw route.

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

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

For a destructive tool with no annotations and no output schema, the description should at minimum explain the effect and risk of deletion. It supplies none of that, leaving the agent unable to judge consequences before invoking 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?

There is a single required parameter whose schema description coverage is 100% ("the id of the requested resource"), so the schema already documents it fully. The description adds no format or sourcing detail beyond the path template, making the baseline 3 appropriate.

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

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

The description only restates the tool name as a raw HTTP endpoint ("DELETE /v1/alternativeDistributionKeys/{id}") with no added explanation of what an alternative distribution key is or what deleting one accomplishes. A verb and resource are technically present, but this is essentially a tautology of the name and path rather than a statement of purpose.

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

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

There is no guidance on when to use this tool, no prerequisites, and no mention of alternatives such as alternative_distribution_keys_get_instance or the update/collection variants in the sibling list. The agent must infer everything from the endpoint string.

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?

No annotations are provided, so the description carries the full behavioral burden, yet it discloses nothing beyond the endpoint path. It says nothing about pagination (limit is a param), how results relate to apps (exists_app filter), auth requirements, or the shape/volume of the read. A pure endpoint echo for an unannotated tool is a transparency failure.

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

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

It is short, but the parenthetical simply duplicates the preceding endpoint path, so the 'structure' is redundant rather than efficient. This is under-specification masquerading as conciseness; the second half earns no 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 3-parameter collection tool with no annotations and no output schema, the description is completely inadequate: it gives no filtering semantics, no pagination note, no indication of what is returned. An agent has nothing to work with beyond the name.

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

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

Schema description coverage is 100%, so the three params (limit, exists_app, fields_alternativeDistributionKeys) are already self-documented in the schema. The description adds no parameter meaning whatsoever, but per the high-coverage baseline of 3, no penalty below that is warranted.

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

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

The description is essentially the raw endpoint string echoed twice ('GET /v1/alternativeDistributionKeys (GET /v1/alternativeDistributionKeys)'), which merely restates what the tool name already encodes. It implies a list/collection fetch but adds no semantic framing beyond 'this is a GET on alternativeDistributionKeys'. No differentiation from sibling create/get_instance/delete_instance tools beyond what the name provides.

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

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

There is no guidance on when to call this versus the many sibling collection/list tools, no mention of required auth or prerequisites, and no exclusions. The only implicit usage signal is the HTTP verb, which is inference rather than stated 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure, and it discloses nothing: no auth requirements, no note on whether the key is sensitive material, no error behavior for an invalid id. A bare URL is not behavioral context.

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

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

It is short, but the single sentence is a verbatim duplication of the same path twice, so half the text is pure waste and nothing is front-loaded beyond the endpoint. Brevity here reflects under-specification, not efficiency.

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 tool with no annotations and no output schema, the description should at minimum say what a key is and what the response contains. It says nothing, leaving the agent entirely dependent on the tool name and schema.

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

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

Schema description coverage is 100%, and the schema already documents both 'id' (the id of the requested resource) and 'fields_alternativeDistributionKeys'. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

The description is only a duplicated REST path, 'GET /v1/alternativeDistributionKeys/{id} (GET /v1/alternativeDistributionKeys/{id})', which restates the tool name rather than explaining what the resource is or what fetching it returns. An agent can infer a read of a single alternative distribution key, but nothing distinguishes it from the sibling get_instance tools beyond the raw URL.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no reference to alternatives such as alternative_distribution_keys_get_collection or apps_alternative_distribution_key_get_to_one_relationship. The agent must infer everything from the name alone.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing: not whether the call is read-only (implied only by the 'GET' token), nor auth requirements, rate limits, or what the returned delta payload contains. A bare route string is inadequate for a mutation-free but undocumented endpoint.

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

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

It is short, but the only content is the same route repeated twice with no added information, so no sentence earns its place. Brevity here reflects under-specification rather than disciplined conciseness.

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

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

For a single-resource GET with a fully documented two-parameter schema, the structured fields cover invocation, but the description supplies no domain context about what an alternative distribution package delta is or how it relates to the sibling version/package tools, leaving the agent unable to distinguish it from adjacent endpoints.

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

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

Schema description coverage is 100% — the 'id' parameter is documented as 'the id of the requested resource' and the sparse-fieldset parameter lists its enum values — so the schema does the heavy lifting. The description adds nothing beyond the path template, but the baseline for fully documented schemas is 3.

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

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

The description is only the raw HTTP route 'GET /v1/alternativeDistributionPackageDeltas/{id}', duplicated in parentheses. It restates the operation already encoded in the tool name (get_instance) and gives no plain-language statement of what an alternative distribution package delta is or what retrieving one yields.

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

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

There is no guidance at all about when to use this tool versus the many sibling relationship tools (e.g. alternative_distribution_package_versions_deltas_get_to_many_relationship) or the other alternative_distribution_package_* getters. Nothing indicates prerequisites or context.

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

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

With no annotations, the description carries the full behavioral burden, yet it only discloses that this is a POST. It says nothing about side effects, required permissions, idempotency, or error behavior for a mutating endpoint. The pointer to the OpenAPI request schema is the only substantive content.

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

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

It is a single short sentence, which is efficient, but it redundantly repeats 'POST /v1/alternativeDistributionPackages' twice in a parenthetical and spends most of its length on a schema cross-reference rather than useful content.

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

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

For a mutation tool with no annotations and no output schema, the description is thin: it does not explain what a request body must contain, what the endpoint returns, or what preconditions exist. The nested JSON:API envelope is pushed entirely to an external OpenAPI document the agent may not have access 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?

There is a single body parameter at 100% schema description coverage, so the schema already carries the documentation burden. The description only points to components.schemas.AlternativeDistributionPackageCreateRequest, which duplicates the schema's own note rather than adding new meaning.

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

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

The description gives the HTTP method and path (POST /v1/alternativeDistributionPackages), from which a create operation on alternative distribution packages can be inferred. However, it never states the purpose in plain terms and does not distinguish this tool from siblings like alternative_distribution_packages_get_instance or versions_get_to_many_related. It is essentially a mechanical verb+path restatement.

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

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

There is no guidance on when to use this tool versus alternatives such as the get_instance variant, and no mention of prerequisites (e.g., an existing app store version). The agent is left to infer usage entirely.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it does not meet it. The GET verb weakly implies a non-destructive read, but nothing is said about authentication, errors for unknown ids, pagination/relationship expansion behavior, or whether the included relationships affect response size.

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

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

It is short, but the parenthetical duplicate of the path is pure waste that earns no place. Nothing is front-loaded except the route string, which the agent already infers from the tool name.

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

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

For a five-parameter read with no annotations and no output schema, the definition is inadequate: it never says what resource is returned or that include/fields_* shape the response. The schema covers parameter formats, but the description leaves an agent with no operating context.

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

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

Schema description coverage is 100%, so every one of the five parameters (id, include, limit_versions, and the two field selectors) is already documented in the schema; baseline 3 applies. The description contributes nothing beyond the route, so it neither compensates nor detracts.

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

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

The description is only the raw HTTP route ("GET /v1/alternativeDistributionPackages/{id}") repeated twice in parentheses. The tool name already says it is a get-by-id for alternative distribution packages, so the description adds no distinguishing information and is effectively a tautology with an endpoint echo.

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 tool rather than the many sibling getters (e.g. alternative_distribution_packages_versions_get_to_many_related, alternative_distribution_package_versions_get_instance) or any prerequisite such as needing a valid package id. No when-to-use and no exclusions are given.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure, and it discloses nothing. It does not mention pagination semantics, authentication requirements, response shape, ordering, or what a 'version state' (COMPLETED/REPLACED) means. A raw endpoint string is the minimum possible behavioral information.

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

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

It is short, but structurally wasteful: the same endpoint string appears twice, once duplicated in parentheses, with no front-loaded statement of intent. Brevity here reflects under-specification rather than disciplined conciseness.

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 10-parameter collection-fetch tool with no output schema and no annotations, so the description is the only place behavioral and selection context could live — and it provides none. The rich schema partially compensates for parameter documentation, but the overall definition is not sufficient to call the tool confidently.

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

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

Schema description coverage is 100%, so all ten parameters (including the include/filter/limit/fields_* enums) are already documented in the schema. The description adds no parameter meaning beyond echoing the {id} path segment, so the baseline of 3 applies.

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

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

The description is essentially a restatement of the tool name as a URL path (GET /v1/alternativeDistributionPackages/{id}/versions, duplicated in parentheses). It conveys the verb and the parent resource, but adds no explanation of what an alternative distribution package version is or how this collection differs from siblings like alternative_distribution_package_versions_get_instance. It reads as tautology rather than a stated purpose.

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

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

No guidance on when to use this tool versus the many related alternatives (e.g. the singular version endpoint or the sibling 'relationship' variant). The URL path implies it lists versions under a package, but nothing tells the agent the conditions that select this tool. Score 2 for absent 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?

With no annotations provided, the description carries the full burden of behavioral disclosure but supplies none. It says nothing about authentication, pagination behavior despite the limit parameter, response shape, or the relationship between alternative distribution packages and their versions.

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

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

The text is short but wasteful: it repeats the identical endpoint path twice in parentheses without adding any explanatory content. Conciseness here reflects under-specification and redundancy rather than efficient communication.

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

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

For a tool with no annotations, no output schema, and many similar sibling endpoints, the description is completely inadequate. An agent would have to rely solely on the tool name and schema to decide whether and how to call it.

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

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

Schema description coverage is 100%, so both the required id and optional limit parameters are already documented in the schema. The description adds no additional parameter meaning, but under the high-coverage baseline this is adequate.

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 only restates the HTTP method and URL path, duplicating the tool name rather than explaining what the tool does in plain language. It does not distinguish this tool from sibling relationship endpoints such as alternative_distribution_packages_versions_get_to_many_related or the get-instance variant.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of the closely named sibling tools that expose similar version-related data. The description provides only the endpoint, leaving selection entirely to inference from the name.

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

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

No annotations are provided, so the description must carry the full behavioral burden, and it conveys nothing beyond the HTTP verb. It does not state whether the retrieval is read-only, what happens with an invalid id, whether fields filtering is required, or anything about the response shape.

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

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

It is short, but the single sentence duplicates the same path twice in parentheses, which is pure waste rather than economy. There is no front-loaded purpose statement, just a raw endpoint string.

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

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

With no annotations, no output schema, and a terse path-only description, an agent has no information about the resource being fetched or what comes back. For a domain-specific resource like an alternative distribution package variant, this is far below the minimum needed to call it confidently.

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

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

Schema description coverage is 100% — the 'id' and 'fields_alternativeDistributionPackageVariants' parameters are both documented in the schema, including the enum of selectable fields. The description adds zero meaning beyond it, so the baseline 3 for fully-covered schemas applies.

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

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

The description only restates the tool name and its URL path ('GET /v1/alternativeDistributionPackageVariants/{id}') twice. There is no plain-language statement of what an 'alternative distribution package variant' is or what retrieving one accomplishes, so it is effectively a tautology that an agent cannot distinguish meaningfully from sibling get_instance tools.

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

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

No guidance whatsoever on when to use this tool versus the many sibling retrieval tools (e.g. alternative_distribution_package_versions_variants_get_to_many_relationship, alternative_distribution_package_deltas_get_instance). No prerequisites, exclusions, or alternatives are mentioned.

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

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

With no annotations supplied, the description carries the full behavioral burden, yet it only reveals the HTTP verb, which implies a read. It does not disclose authentication requirements, pagination behavior via limit, whether the parent version must exist, or how deltas relate to the package version. Minimal implicit read-only signal only.

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 text is short but the entire endpoint string is duplicated verbatim inside parentheses, which is pure waste. It is front-loaded with the verb and path, but the redundant parenthetical should have been replaced with actual explanatory content.

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

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

For a paginated, field-selectable collection endpoint with no output schema and no annotations, the description omits return shape, pagination semantics, and its relationship to the deltas/variants sibling endpoints. An agent could call it, but only by guessing at everything beyond the URL.

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

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

Schema description coverage is 100%, so all three parameters (id, limit, fields_alternativeDistributionPackageDeltas) are documented in the schema itself. The description contributes nothing beyond this, which matches the baseline 3 when the schema does the heavy lifting.

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

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

The description only echoes the HTTP method and path ('GET /v1/alternativeDistributionPackageVersions/{id}/deltas'), restating the tool name rather than explaining what a 'delta' of an alternative distribution package version is. It does imply a read of a specific resource, but gives no natural-language statement of purpose and cannot be distinguished from the sibling alternative_distribution_package_versions_deltas_get_to_many_relationship.

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

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

There is no guidance on when to use this tool versus the many sibling relation endpoints (variants_get_to_many_related, deltas_get_to_many_relationship, packages_versions_get_to_many_related). No prerequisites, no when-not conditions, nothing to route the agent.

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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing: no note that this is a read-only relationship fetch, no pagination behavior despite the 'limit' parameter, no auth requirements, and no relationship-vs-related distinction. The only implicit signal is the 'GET' verb in the path.

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

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

It is short, but it is pure redundancy: the same route string appears twice with no added information, so the second copy earns nothing. There is no front-loaded purpose sentence to orient the reader.

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

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

With no annotations, no output schema, and a description consisting only of a repeated URL, the definition is inadequate for an agent to know what the call returns or how to interpret it. A relationship endpoint in particular needs explanation of the linkage-resource semantics, which is entirely absent.

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

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

Schema description coverage is 100% for both parameters ('id' and 'limit'), so the schema already documents them fully; per the baseline rule this yields a 3. The description adds no syntax or format detail beyond the raw path template, so it neither helps nor harms.

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

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

The description is literally the HTTP route duplicated verbatim in parentheses: 'GET /v1/alternativeDistributionPackageVersions/{id}/relationships/deltas (...same...)'. It restates what the tool name already encodes and gives no plain-language statement of what a 'deltas relationship' fetch returns or why an agent would call it, so it reads as a tautology rather than a purpose statement.

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

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

There is no when-to-use guidance, no mention of the sibling tools (e.g. alternative_distribution_package_versions_deltas_get_to_many_related, or the variants relationship siblings), and no indication of when this relationship endpoint is preferred over the related endpoint. Nothing routes the agent among alternatives.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure, yet it offers nothing. It does not mention authentication requirements, pagination/sparse-field behavior, or what the call returns. The bare URL path is not behavioral context.

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

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

It is short, but the parenthetical repeats the identical string with zero added information, which is pure noise rather than concise front-loading. Brevity here reflects under-specification, not efficiency.

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

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

For an 8-parameter retrieval tool with no annotations and no output schema, the description should at minimum explain the resource and how the include/fields/limit parameters shape the response. None of that is present.

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

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

Schema description coverage is 100%, so all 8 parameters (id, include, limit_deltas, limit_variants, and the fields_* selectors) are already documented in the schema. The description adds nothing, but the high coverage establishes the baseline of 3.

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

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

The description is essentially the tool name re-expressed as a REST path, duplicated verbatim in parentheses. It conveys only that this is a GET by id, which the name 'get_instance' already implies, and gives no explanation of what an alternative distribution package version actually is or how it differs from sibling resources.

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

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

There is no guidance whatsoever on when to use this tool versus the many sibling retrieval tools (e.g. alternative_distribution_package_versions_variants_get_to_many_related, alternative_distribution_packages_versions_get_to_many_related). No prerequisites or context are stated.

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

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

No annotations are provided, so the description carries the full burden, and it discloses nothing about pagination behavior despite a 'limit' parameter, filtering semantics, permissions, or what a 'variant' represents. The only content is a duplicated URL string.

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

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

It is short, but the parenthetical duplicates the exact same endpoint string, so the single sentence contains zero informational value and one redundant clause. Brevity here reflects under-specification rather than effective conciseness.

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

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

With no annotations, no output schema, and a relationship-style endpoint requiring a parent resource id, the description should at minimum explain the resource relationship and pagination. It provides none of that, leaving the agent to infer everything from the name alone.

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

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

Schema description coverage is 100%, so the schema already documents 'id', 'limit', and 'fields_alternativeDistributionPackageVariants' clearly. Per the baseline rule for high coverage, a 3 is appropriate even though the description adds no parameter meaning of its own.

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

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

The description is only the HTTP method plus path echoed twice: 'GET /v1/alternativeDistributionPackageVersions/{id}/variants (GET /v1/alternativeDistributionPackageVersions/{id}/variants)'. This restates the tool name and endpoint verbatim rather than explaining what the tool returns or why an agent would use it, which is the definition of a tautological description.

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, when-not-to-use, or alternative is mentioned. The sibling set contains near-identical tools such as alternative_distribution_package_versions_deltas_get_to_many_related and ..._variants_get_to_many_relationship, and nothing here helps the agent choose 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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing. The GET verb implies read-only, but there is no statement about auth requirements, pagination behavior, or what relationship data (identifiers vs. full resources) is returned. The one hint, that this is a to-many relationship, comes only from the tool name.

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?

There is only one sentence, but it is pure duplication: the same path is written twice, the parenthetical repetition adding zero information. Short, but the space is not used to convey anything, so it is under-specification rather than genuine conciseness.

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 relationship endpoint with no annotations and no output schema, the description should explain what the relationship resolves to and how pagination works. It offers none of this, so an agent cannot call it correctly without reading the underlying API docs.

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

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

Schema description coverage is 100% for both parameters (id and limit), so the schema already documents the required resource id and the page-size limit. The description adds nothing on top of that, which lands at the baseline for high coverage.

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

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

The description is essentially the tool name restated as a raw HTTP path, duplicated verbatim inside parentheses. It identifies the endpoint (GET on alternativeDistributionPackageVersions/{id}/relationships/variants) but adds no explanation of what 'variants' are or what the call returns, so it is tautological rather than descriptive.

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 conditions, no mention of the closely related sibling alternative_distribution_package_versions_variants_get_to_many_related, which an agent would otherwise confuse with this relationship endpoint. The description gives nothing to route on.

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 are absent, so the description carries the full burden of behavioral disclosure, yet it discloses nothing: no read-only nature, no pagination/field-selection behavior, no note that report instances are the data artifacts produced by analytics report requests, and no hint about what the response contains.

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

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

It is short, but the single sentence duplicates itself (the same path printed twice) and carries zero informational payload. Brevity here is under-specification rather than conciseness.

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

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

With no annotations and no output schema, the description needed to explain what an analytics report instance is and what fetching one returns. It provides none of that, leaving the agent unable to use the tool confidently beyond the mechanical GET semantics.

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

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

Schema description coverage is 100% and both parameters (id, fields_analyticsReportInstances) are documented in the schema itself, including the enum of fields. The description adds nothing beyond that, so the baseline 3 applies.

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

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

The description is a bare restatement of the tool name as an HTTP path: 'GET /v1/analyticsReportInstances/{id} (GET /v1/analyticsReportInstances/{id})'. It conveys only that a single analyticsReportInstance is fetched by id, which the name already implies, and does nothing to distinguish it from siblings like analytics_reports_instances_get_to_many_related or analytics_report_instance_wait.

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

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

No guidance whatsoever on when to use this tool, when to use the collection/related variants instead, or what prerequisites (ids derived from a report request) are needed. The agent must infer everything from the tool name.

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

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

No annotations are provided, so the description carries the full behavioral burden. The only signal is the HTTP verb GET in the route, implying a read-only operation; nothing is said about pagination (the limit param implies it), authentication requirements, or rate limits.

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

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

Extremely short but the parenthetical literally duplicates the identical route, which is pure waste. This is under-specification masquerading as brevity rather than economical writing.

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 relationship-list endpoint with no annotations and no output schema, the description says nothing about what a segment contains, how results are paged, or how it differs from the "_relationship" counterpart. The schema covers inputs, but the description leaves the agent without the context needed to call it confidently.

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

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

Schema description coverage is 100% and all three parameters (id, limit, fields_analyticsReportSegments) are documented in the schema itself. The description adds no parameter meaning, so the baseline of 3 applies.

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

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

The description is just the HTTP route restated twice: "GET /v1/analyticsReportInstances/{id}/segments (GET /v1/analyticsReportInstances/{id}/segments)". It does convey the resource (segments of an analytics report instance) but is effectively a tautology that adds no plain-language statement of what the tool does, and it does not distinguish this "_related" variant from the sibling analytics_report_instances_segments_get_to_many_relationship.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the near-identical sibling endpoint that an agent must choose between. The description offers nothing to route selection.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing: no read-only confirmation, no pagination behavior (despite a limit parameter), no indication of what the relationship payload contains or what permissions are needed. The route string alone conveys no behavioral traits.

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

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

It is short, but it is not concise in any useful sense: the identical route string is printed twice with no added information. The single sentence is pure duplication rather than front-loaded 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?

For a relationship-fetch endpoint with no annotations and no output schema, the description should at minimum explain what segments are and how the related-vs-relationship variant differs. It supplies none of that, leaving the agent to infer everything from the name.

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

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

Schema description coverage is 100% — both 'id' and 'limit' are documented in the schema itself. The description adds nothing beyond the schema, so the baseline 3 applies.

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

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

The description is nothing but the raw HTTP route, 'GET /v1/analyticsReportInstances/{id}/relationships/segments', repeated verbatim in parentheses. It restates the tool name in URL form rather than stating in plain language what the tool does (retrieve the segment relationships for an analytics report instance). No verb+resource phrasing an agent can act on.

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, when-not-to-use, or alternative-routing guidance at all. The sibling set contains closely named tools (analytics_report_instances_segments_get_to_many_related, analytics_report_segments_get_instance), and the description gives no basis 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?

With no annotations, the description carries the full burden and does disclose meaningful behavior: it polls, it stops on COMPLETED/FAILED or timeout, and it returns the final payload. However, it omits what happens on timeout (error vs last payload), any default/limit values for the timeout and interval, and any rate-limit or auth expectations for a polling loop.

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

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

Two sentences with zero filler; the action and termination condition are front-loaded and the return-value sentence adds information rather than restating the name.

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

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

For a three-parameter async-polling tool with no annotations, no output schema, and undocumented parameters, the description covers the core semantics but leaves key operational gaps: timeout-outcome behavior, polling interval meaning, and defaults. Adequate but incomplete.

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 compensate and it only partly does: 'a timeout expires' maps loosely to timeoutMs, but pollIntervalMs is never explained, the id format/type is not clarified, and no defaults or units are given for the timing parameters.

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

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

States a specific verb ('Poll') and resource ('analytics report instance') plus the terminal conditions (COMPLETED or FAILED) that define success. This implicitly separates it from the single-shot sibling analytics_report_instances_get_instance, but it never names that sibling or any alternative, so differentiation is left to inference.

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 polling-until-terminal wording implies the use case (waiting on an async report job), but the description gives no explicit when-to-use guidance, no prerequisites (e.g. a report instance must already exist), and no statement of when a plain get_instance fetch is preferable.

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?

No annotations are provided, so the description carries the full behavioral burden, yet it discloses almost nothing: no indication of what the created request triggers, whether it is idempotent, what permissions are required, or what the response contains. The only behavioral signal is the implicit 'POST = mutation', which comes from the raw HTTP verb rather than an explicit statement.

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

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

It is short and front-loads the endpoint, but it wastes words by stating the identical path twice in parentheses, and every sentence is low value. Brevity here reflects under-specification rather than disciplined editing.

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

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

For a create operation with a nested JSON:API envelope (additionalProperties: {}, i.e. opaque), no annotations, and no output schema, the description leaves the agent without the body structure it needs to actually invoke the tool. Deferring to an external OpenAPI component the agent may not have access to is not sufficient.

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

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

There is a single required body parameter and schema description coverage is 100%, so the schema already documents the parameter and the baseline of 3 applies. The description only repeats the schema's own pointer to components.schemas.AnalyticsReportRequestCreateRequest, adding no additional semantic detail about the 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?

The description essentially restates the HTTP verb and path ('POST /v1/analyticsReportRequests'), which conveys that a report request is created but explains nothing about what an analytics report request is or what creating one accomplishes. It offers no differentiation from siblings such as analytics_report_requests_get_instance, analytics_report_requests_delete_instance, or analytics_report_requests_reports_get_to_many_relationship. This is close to a tautology of the tool name.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives among the many sibling analytics/newer-report tools. The only 'guidance' is a pointer to the OpenAPI schema for request body shape, which is not usage context.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses nothing about irreversibility, whether related report instances are cascaded/deleted, required auth scopes, or failure modes for a destructive operation.

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

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

It is short, but it wastes the entire budget by duplicating the same path string twice with zero information gain. Under-specification, not conciseness.

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

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

For a destructive endpoint with no annotations and no output schema, the description should explain consequences and prerequisites. It provides none, leaving an agent unable to safely decide whether 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?

There is one parameter with 100% schema description coverage ('the id of the requested resource'), so baseline is 3. The description adds no further meaning about the id beyond what the schema already states.

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

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

The description is just the HTTP verb and path repeated twice, e.g., 'DELETE /v1/analyticsReportRequests/{id}'. It does convey delete-on-a-specific-report-request, but it is essentially a restatement of the tool name rather than an explanation of what the operation means in domain terms.

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

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

No guidance on when to use this tool, when not to, or how it relates to siblings like analytics_report_requests_get_instance or analytics_report_requests_reports_get_to_many_relationship. The agent gets no routing signal.

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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing: no authentication requirements, no rate limits, no note on whether the resource may be absent, and no statement of what is returned. The path string itself is not behavioral disclosure.

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

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

It is short, but the parenthetical duplicates the sentence word-for-word, so half the text is pure redundancy rather than earned conciseness. Brevity here comes from omission, not from tight editing.

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

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

A five-parameter read tool with no annotations and no output schema needs the description to explain retrieval semantics and the sparse-fieldset/include behavior; instead it supplies only a path. Nothing an agent needs in order to call this correctly is present.

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

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

Schema description coverage is 100%, so the schema already documents id, include, limit_reports and both fields_* filters. The description adds nothing beyond that, which lands at the baseline of 3 for high-coverage schemas.

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

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

The description is a verbatim restatement of the tool name as a REST path, duplicated inside parentheses. It tells the agent nothing beyond 'GET this resource by id' — no scope, no mention of what an analytics report request is, and no differentiation from the dozens of neighboring analytics_report_* siblings. This is tautology rather than a stated purpose.

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

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

No indication of when to call this versus alternatives. The sibling set contains analytics_report_requests_reports_get_to_many_related, apps_analytics_report_requests_get_to_many_related, analytics_report_requests_create_instance and others; the description offers no routing guidance whatsoever.

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?

No annotations are provided, so the description carries the entire burden and delivers nothing: 'GET' hints at a read, but there is no mention of pagination behavior (despite a limit parameter), filtering semantics, auth requirements, or result shape. For a paged collection endpoint this is a serious gap.

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

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

The single sentence is not concise so much as content-free — it repeats the same path twice in parentheses without adding information. There is no front-loaded statement of purpose to structure around.

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

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

With no annotations, no output schema, and a bare path restatement, the agent has nothing to work with beyond the schema. Nothing about pagination, filtering combinations, or error behavior 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 description coverage is 100%, so all five parameters (id, limit, filter_name, filter_category, fields_analyticsReports) are already documented in the schema. Baseline 3 applies; the description adds no meaning beyond what the schema provides.

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

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

The description is a verbatim restatement of the HTTP method and path, which duplicates what the tool name already encodes. It never says in plain language what a caller gets back — a list of analytics reports belonging to a report request — nor what distinguishes it from the sibling '..._reports_get_to_many_relationship'.

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

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

There is no guidance about when to use this tool, what prerequisite state is needed (a valid report request id), or how it differs from the relationship-suffixed sibling. The agent is left to infer everything from the name.

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

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

No annotations are provided, so the description carries the full burden, yet it discloses nothing about behavior. It does not mention that this is a read-only relationship fetch, pagination semantics, auth requirements, or what the response contains beyond the bare GET path.

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

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

The description is short but consists entirely of a path duplicated verbatim in parentheses, which is pure redundancy with zero informational value. Nothing is front-loaded because there is no explanatory content at all.

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

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

With no annotations and no output schema, the description should explain what the endpoint returns and how pagination behaves, but it does neither. For a relationship-listing tool in a large sibling set, the raw path alone is inadequate for correct invocation.

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

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

Schema description coverage is 100% for both parameters (id and limit), so the schema already documents them fully. The description adds no syntax, format, or meaning beyond what the schema provides, making the baseline of 3 appropriate.

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

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

The description is a raw HTTP path repeated twice in parentheses, with no natural-language verb or resource statement. An agent can infer it reads the 'reports' relationship of an analyticsReportRequest, but this is a restatement of the name/URL rather than an explanation of purpose.

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

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

There is no guidance on when to use this tool versus siblings such as analytics_report_requests_reports_get_to_many_related or analytics_report_requests_get_instance. No context, no prerequisites, no exclusions are provided.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure, and it discloses nothing. It does not state auth requirements, whether the operation is read-only (only inferable from 'GET'), rate limits, or error behavior for a missing id.

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

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

It is short, but the content is a verbatim endpoint path printed twice in parentheses, which is redundant noise rather than front-loaded signal. Brevity here reflects under-specification, not efficient communication.

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

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

The tool is a simple single-resource GET with full schema coverage and no output schema, so it needs little, but the description still fails to say what an analytics report segment is or why an agent would fetch one. Naming only the HTTP route leaves the resource semantically opaque.

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

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

Schema description coverage is 100%, so both the required 'id' and the optional 'fields_analyticsReportSegments' are fully documented in the schema itself. The description adds no additional syntax, format, or filtering meaning, so the baseline of 3 applies.

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

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

The description is just the raw endpoint path 'GET /v1/analyticsReportSegments/{id}' repeated twice, which restates the tool name rather than explaining what the resource is or what a 'segment' contains. It does convey a read of a single analytics report segment by id, but provides no purpose beyond what the name already implies.

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

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

There is no guidance on when to use this tool versus the many sibling 'get_instance'/'get_to_many' analytics tools, no prerequisites, and no indication of when it should not be used. The agent is left to infer everything from the URL.

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

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

With no annotations, the description carries the full burden, and it discloses nothing beyond the 'GET' verb (which weakly implies a read). It does not say whether the lookup is scoped, what happens on a missing id, whether the response is cached, or which auth/app scopes are needed.

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

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

Very short, but the single sentence is pure redundancy: the route appears twice in parentheses with no added information. Brevity here comes from omission rather than from efficient front-loading.

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

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

There is no output schema and no annotations, so the description is the only place an agent could learn what this call returns and when to make it. It provides neither, leaving a bare REST route for a resource that is otherwise ambiguous among many analytics-related siblings.

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

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

Schema description coverage is 100% and both parameters (id and fields_analyticsReports) are documented in the schema with enum values for fields. The description adds no meaning beyond the schema, so the baseline 3 applies.

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

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

The description is just the HTTP route repeated twice: 'GET /v1/analyticsReports/{id}'. It restates the tool name and path but never says what an analytics report is or what retrieving one returns. An agent learns only that some resource with that id exists.

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, when-not-to-use, or alternatives are given. Sibling tools like analytics_report_instances_get_instance and analytics_reports_instances_get_to_many_relationship sit alongside it, and nothing in the definition helps an agent choose 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure, and it supplies none. It does not mention pagination (despite the limit parameter), auth requirements, default page sizes, or what the response contains — a bare path conveys no behavioral context.

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

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

The text is short but the only content is a verbatim repeat of the path in parentheses, which is pure redundancy rather than concision. It is under-specified, not efficiently front-loaded.

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

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

For a five-parameter list endpoint with no annotations and no output schema, an agent needs to know about pagination, filtering behavior, and return shape. The description provides none of this, so it is inadequate for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including filters, fields, and limit. The description adds nothing beyond that, which lands at the baseline of 3 when structured fields do the work.

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

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

The description is nothing more than the raw endpoint path duplicated inside parentheses, so it effectively restates the tool name rather than explaining what the tool does. An agent can infer it lists instances of an analytics report, but only by decoding the URL, not from any prose.

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

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

There is no when-to-use guidance and no differentiation from close siblings such as analytics_reports_instances_get_to_many_relationship, analytics_report_instances_get_instance, and analytics_reports_get_instance. The path implies the resource but offers no selection criteria.

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?

No annotations are provided, so the description carries the full burden, yet it discloses essentially nothing. The 'GET' verb weakly implies a read-only, non-destructive operation, and the presence of a limit parameter is implied by the schema, but there is no statement about authentication, pagination behavior, or what relationship data is 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?

The description is short, but every character is wasted: the same path is printed twice inside a redundant parenthetical, and none of it earns its place by adding meaning. Brevity here reflects under-specification rather than genuine conciseness.

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 relationship-fetch tool with no output schema and no annotations, the description should at minimum explain what an 'instances' relationship yields and how pagination works. It supplies none of that, leaving the agent unable to reason about the call beyond the path itself.

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

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

Schema description coverage is 100% for both parameters ('id' and 'limit'), so the schema already fully documents them and the baseline of 3 applies. The description adds no parameter meaning whatsoever beyond what the schema supplies.

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

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

The description is nothing but the raw HTTP path repeated twice in parentheses: 'GET /v1/analyticsReports/{id}/relationships/instances (GET /v1/analyticsReports/{id}/relationships/instances)'. It technically contains a verb (GET) and a resource, but that is a tautological restatement of the tool name rather than an explanation of what the tool does, and it gives no basis for distinguishing it from the near-identical sibling analytics_reports_instances_get_to_many_related.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the -related vs -relationship sibling that an agent must choose between. The endpoint path is the only information offered, leaving selection entirely to inference from the name.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, and it discloses almost nothing: no side effects, no auth/permission requirements, no indication of whether the mapping must reference existing apps, and no return behavior. The only signal is the implied POST-mutates semantics.

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

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

It is short and front-loads the endpoint, but the parenthetical redundantly repeats the identical path and the body-shape pointer duplicates the schema description, so not every token 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 create/mutation tool with no annotations, no output schema, and a nested-object body, the description should explain what the resource represents and what a valid creation requires. Instead it punts entirely to an external OpenAPI component, leaving the agent unable to call it correctly without outside documentation.

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

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

Schema description coverage is 100% and the single body parameter is documented there. The description repeats the same 'see components.schemas.AndroidToIosAppMappingDetailCreateRequest' pointer without adding any field-level meaning, so it neither helps nor harms beyond the baseline for high-coverage schemas.

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

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

The description identifies the resource (androidToIosAppMappingDetails) and the HTTP verb (POST), which implies creation, so an agent can roughly tell what it does. However, it never explains in plain language what an Android-to-iOS app mapping detail is or what creating one accomplishes; it merely restates the endpoint path.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the sibling tools (get/update/delete instance for the same resource) that an agent must choose between. Usage must be inferred entirely from the name and HTTP method.

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?

No annotations are provided, so the description carries the full burden, and it discloses nothing: not whether the deletion is permanent or reversible, not what permissions are required, and not what happens to dependent mappings. A destructive operation documented only by its URL is a serious gap.

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

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

The text is short but wasteful: the identical endpoint string appears twice in parentheses, so there is no front-loaded intent, just a duplicated URL fragment.

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

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

For a destructive endpoint with no annotations, no output schema, and no supporting text, the description omits everything an agent needs to act safely: irreversibility, auth requirements, and effect on related resources.

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

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

Schema coverage is 100% and the single `id` parameter is documented in the schema as "the id of the requested resource." The description's path template merely repeats that {id} is required, so it neither adds nor detracts from the schema; baseline 3 applies.

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

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

The description is only the HTTP method and path ("DELETE /v1/androidToIosAppMappingDetails/{id}"), which restates the tool name rather than describing what deleting this resource accomplishes. It does convey the verb and resource, but adds no distinguishing information beyond the identifier itself.

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

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

There is no guidance on when to delete an Android-to-iOS app mapping versus updating it (android_to_ios_app_mapping_details_update_instance) or creating a new one. No prerequisites, no exclusions, no context of any kind.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure, and it says nothing. It does not mention authentication requirements, error behavior for unknown ids, pagination/sparse-field semantics of the fields_... parameter, or output shape.

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

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

It is very short, but the content is the same route string duplicated inside parentheses, which is pure redundancy rather than front-loaded information. Brevity here reflects under-specification, not efficient prose.

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

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

A single-resource read tool with no annotations, no output schema, and a description consisting only of the URL fragment leaves the agent without the minimum context needed to invoke it confidently (auth, response shape, sparse-fieldset behavior).

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

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

Schema description coverage is 100%: both 'id' and 'fields_androidToIosAppMappingDetails' carry their own descriptions in the schema. With the schema doing all the work, the baseline of 3 applies; the description adds no additional parameter semantics.

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

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

The description restates the tool name/HTTP route ('GET /v1/androidToIosAppMappingDetails/{id}') rather than describing in plain terms what is retrieved. It does reveal the operation is a read of a single androidToIosAppMappingDetails resource by id, but that is inferable from the name alone and adds no differentiation from sibling create/update/delete tools.

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

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

There is no guidance about when to use this tool versus the sibling android_to_ios_app_mapping_details_create/update/delete_instance tools or the apps_android_to_ios_app_mapping_details_get_to_many relationship tool. Nothing indicates prerequisites or context.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it only states the verb and path. It hints at a JSON:API envelope requirement for the body, which is mild useful context, but omits partial-update semantics (what happens to omitted fields), auth/permission requirements, error behavior, and any destructive or irreversible effects.

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

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

The description is short and front-loads the operation, which is good, but the path is redundantly repeated in parentheses and the sentence spends its budget pointing at a schema component rather than adding 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 mutation tool with no annotations and no output schema, the definition should clarify what gets modified, partial-update behavior, and requirements. Instead it defers entirely to an external OpenAPI component reference the agent may not be able to resolve, leaving the update semantics underspecified.

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

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

Schema description coverage is 100%, so both parameters (id and body) are already documented in the schema. The description adds only that the body follows a JSON:API envelope and references the same components.schemas component the schema already points to, so it adds essentially nothing beyond structured data.

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

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

The description names the operation via the HTTP verb PATCH and the resource path /v1/androidToIosAppMappingDetails/{id}, so an agent can infer 'update an existing Android-to-iOS app mapping detail'. However, it is essentially a restatement of the tool name with no explanation of what the mapping detail represents or what can be updated, and it does not distinguish itself from the sibling create/get/delete instance tools beyond the verb.

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

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

There is no when-to-use guidance, no mention of prerequisites or required permissions, and no reference to the sibling create/get/delete tools for the same resource. The agent is left to infer that PATCH means partial update and that an existing id is required.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure and supplies almost none. The 'GET' verb implies a read-only operation, which is the sole behavioral signal, but there is no mention of authentication requirements, error behavior for a missing id, or what the response contains.

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

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

The text is short but entirely redundant, repeating the same route twice in a parenthetical with zero informational gain. Brevity here reflects under-specification rather than disciplined conciseness.

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

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

With no annotations and no output schema, the description is the only source of behavioral context, and it fails to explain return shape, sparseness via the fields parameter, or error conditions. For a two-parameter retrieval endpoint it is materially incomplete.

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

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

Schema description coverage is 100%, so the schema already documents both 'id' and 'fields_appAssetLibraries' (including the enum values images/videos). The description adds nothing beyond echoing the path parameter, so the baseline 3 for a fully documented schema is appropriate.

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

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

The description is just the HTTP route repeated twice ("GET /v1/appAssetLibraries/{id} (GET /v1/appAssetLibraries/{id})"), which restates the tool name rather than describing the operation in words. An agent can infer 'fetch one app asset library' from the name and path, but the description itself adds no explanatory content and does nothing to distinguish it from siblings like app_asset_libraries_images_get_to_many_related.

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 tool versus alternatives such as apps_asset_library_get_to_one_relationship or app_asset_library_images_get_instance. The only implicit cue is the '{id}' path template, which hints at single-resource retrieval but gives no conditional 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?

No annotations are provided, so the description carries the full behavioral burden, yet it discloses nothing about pagination, default/max limits, sorting behavior, or what a GET returns. A raw path echo provides zero behavioral context.

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

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

It is short, but the only content is a duplicated path string, so the 'conciseness' reflects emptiness rather than disciplined structure. There is nothing front-loaded to help an agent.

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 12-parameter list endpoint with no annotations and no output schema, the description should at minimum state that it returns a collection of images for the given asset library and note pagination. It omits all of this, leaving the schema to do essentially all the work.

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

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

Schema description coverage is 100%, so all 12 parameters (sort, limit, include, filter_*, fields_*) are already documented in the schema. Per the baseline rule, a 3 is appropriate; the description adds no parameter meaning whatsoever.

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

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

The description is only the raw HTTP verb and path 'GET /v1/appAssetLibraries/{id}/images' repeated verbatim in parentheses. It conveys no resource meaning beyond what the tool name already encodes, making it a near-tautology rather than a stated purpose.

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

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

There is no when-to-use guidance, no exclusions, and no mention of sibling alternatives such as app_asset_libraries_images_get_to_many_relationship or app_asset_libraries_videos_get_to_many_related. Nothing tells an agent when this endpoint is the right choice.

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

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

No annotations are provided, so the description carries the full burden. The 'GET' prefix weakly implies a read-only fetch, but nothing is said about pagination behavior, relationship-vs-resource payload shape, or permissions on the asset library. For an unannotated tool this is a substantial gap.

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

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

It is short but wastes its only sentence on a verbatim duplicate of the same endpoint string in parentheses. There is no front-loaded explanation of what the call returns, so brevity here is under-specification 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?

With no annotations, no output schema, and a confusingly similar sibling pair (relationship vs related), the description should explain the relationship-endpoint semantics. The endpoint path gives only minimal orientation and leaves the agent guessing about what the call actually returns.

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

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

Schema coverage is 100% with documented 'id' and 'limit' fields, so the schema already does the work; per the baseline rule this scores 3. The description itself contributes nothing about pagination via limit or how id must resolve to an asset library.

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

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

The description is only the raw endpoint 'GET /v1/appAssetLibraries/{id}/relationships/images', repeated verbatim in parentheses. It restates the tool name rather than explaining in plain language that it lists the images in an App Asset Library; the agent gets no verb-plus-resource statement beyond decoding the URL.

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

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

There is no guidance on when to use this tool, no prerequisites, and no mention of the closely-named sibling app_asset_libraries_images_get_to_many_related or videos_get_to_many_relationship, which are equally plausible choices. Nothing helps the agent choose among near-identical 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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing: no read-only confirmation, no pagination behavior, no auth requirements, no note on whether included relationships expand the payload. For a 12-parameter read endpoint with zero annotation coverage this is a complete gap.

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

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

It is short, but the economy comes from under-specification rather than tight writing, and the endpoint is duplicated twice with no added information. Nothing is front-loaded because there is nothing to load.

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

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

A 12-parameter collection endpoint with no annotations and no output schema needs the description to explain what is returned and how filtering/sorting/inclusion interact. The description supplies none of that, leaving the agent unable to call it confidently.

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

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

Schema description coverage is 100%, so all 12 parameters (id, sort, limit, include, filters, fields, limit_placements) are documented in the schema itself. The description adds no semantic value beyond that, but the baseline of 3 applies when the schema does the heavy lifting.

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

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

The description is a bare restatement of the HTTP method and path, duplicated verbatim in parentheses. It implies 'list videos for an app asset library' only through the URL tokens, never stating the purpose in prose. This is tautological with the tool name rather than a clear statement of what the tool does.

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

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

There is no when-to-use guidance, no mention of alternatives, and no differentiation from siblings such as app_asset_libraries_videos_get_to_many_relationship or app_asset_library_videos_get_instance. The agent is left to infer everything from the name alone.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing: not the read-only nature, not pagination semantics for the 'limit' parameter, not rate limits, not the shape or count of what is returned. The bare route is the only signal.

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

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

It is short, but the sentence is printed twice inside parentheses, which is pure redundancy rather than economy. Nothing is front-loaded beyond the raw route.

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 relationship-list endpoint with no annotations and no output schema, the description should at minimum say what is listed and how pagination works. Instead it supplies only the route, leaving the agent without the context needed to call it confidently.

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

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

Schema description coverage is 100%, so both parameters ('id' and 'limit') are already documented in the schema; the description adds no format, scope, or pagination detail beyond it. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description is a verbatim restatement of the tool name rendered as an HTTP route: 'GET /v1/appAssetLibraries/{id}/relationships/videos'. It conveys no more than the name already does, and does not explain the relationship-vs-related distinction against siblings like app_asset_libraries_videos_get_to_many_related.

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

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

There is no when-to-use guidance at all, no mention of prerequisites, and no routing between this relationship endpoint and its near-identical sibling app_asset_libraries_videos_get_to_many_related. The agent is left to infer everything from the path string.

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?

No annotations are provided, so the description carries the full disclosure burden and delivers almost none. It hints that the payload is a JSON:API envelope, but says nothing about auth/permissions, whether the call is idempotent, side effects, or failure modes for what is clearly a mutating POST.

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

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

It is short and front-loads the route, but the parenthetical '(POST /v1/appAssetLibraryImages)' duplicates the text immediately preceding it verbatim. That redundant clause is pure waste, though the overall length is not excessive.

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

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

For a mutating create with a nested, loosely-typed body, no annotations, and no output schema, the description offloads everything to an external OpenAPI component reference the agent may not be able to resolve. The JSON:API envelope requirements and required fields are never surfaced inline.

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

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

There is only one parameter ('body') and the schema description coverage is 100%, so the baseline of 3 applies. The description merely repeats the schema's pointer to components.schemas.AppAssetLibraryImageCreateRequest without adding any field-level or envelope detail of its own.

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

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

The description is essentially the tool name restated as an HTTP route: 'POST /v1/appAssetLibraryImages' adds no plain-language purpose beyond the 'create_instance' in the name. It never explains what an app asset library image is or what creating one accomplishes, so it does little to separate this from the update/get/delete 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?

There is no when-to-use guidance at all. With siblings like app_asset_library_images_update_instance, app_asset_library_images_get_instance, and app_asset_library_images_delete_instance present, the description gives the agent nothing to disambiguate create vs. update vs. fetch.

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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing: not that the operation is destructive, whether deletion is reversible, what related placements or references are affected, or what permissions are required. A single path string is inadequate for a delete operation.

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

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

It is a single short line and front-loads the method and path, but the parenthetical repetition of the identical endpoint is pure waste. Minimal, but not because it is well-edited.

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

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

For a destructive tool with no annotations and no output schema, the description should explain consequences and preconditions. It supplies none, leaving the agent without the context needed to call it safely.

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