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

Annotations already flag destructiveHint=true and openWorldHint=true, but the description adds real context beyond them: auth, User-Agent and sellerId are injected automatically from the store, "*" is read-only, and dryRun:true returns the built URL/body without sending. It does not discuss rate limits, error/partial-failure behavior across multiple stores, or retries.

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?

Information is front-loaded: the tool's purpose, then the auto-injected credentials, then the prerequisite call, then the store and dryRun semantics. It is dense but each sentence carries distinct operational value; only minor tightening is possible.

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

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

For a generic destructive dispatcher with 9 parameters and no output schema, the description covers the critical unknowns: scope of stores, read/write permission gating, auth injection, and a safe dryRun preview. Missing only multi-store failure semantics and response-shape expectations, which matter less given the parameterized, open-world nature of the tool.

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

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

Schema coverage is 78%, so most parameters (body, query, headers, formData, pathParams, maxResponseChars) are already documented structurally. The description adds meaning for store and dryRun — notably that dryRun shows the generated URL/body without sending — but leaves the remaining parameters unaddressed, so the baseline 3 is appropriate.

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

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

States a specific verb and resource: executes any Trendyol API operation identified by operationId, on behalf of a chosen store. It distinguishes itself from siblings by naming trendyol_get_operation (for parameter discovery) and trendyol_list_stores (for store names), so an agent can tell it apart without opening another schema.

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

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

Explicitly says to call trendyol_get_operation first to learn parameters, defines the store argument's three modes (name, empty = default, "*" = all stores for reads only), and states that write operations run only on stores with write permission. Prerequisites and constraints are spelled out rather than implied.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false, so safety is already covered; the description adds genuine value by detailing the shape of the payload returned (schemas, required-field asterisk convention, examples, TS code). With no output schema present, this return-content disclosure is exactly the kind of context the description should carry, though it says nothing about size or truncation of large operation definitions.

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

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

A single dense sentence with the resource named first and the returned artifacts listed after the colon, so nothing is wasted. The trailing enumeration is long but each item is informative, and the '*' convention note 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 read-only lookup tool with no output schema, the description successfully enumerates what comes back and how required fields are marked, which is enough for an agent to call it correctly. Only minor gaps remain: no mention of behavior for an unknown operationId or of response size limits.

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 operationId (with concrete examples) and rawSchema (raw JSON Schema vs. simplified draft) are already documented in the schema. The description adds only the output-side note about required fields being marked with '*', not new parameter semantics. Baseline 3 applies.

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

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

States a specific verb+resource: it returns the full definition of a single API operation, enumerating exactly what is included (URLs, parameters, request body schema, response schema, examples, TypeScript sample). It is clearly distinct from trendyol_list_operations (enumeration) and trendyol_call_api (execution), but it never explicitly names those siblings to sharpen the boundary.

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

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

Usage is implied rather than stated: the mention of full schemas, examples and code suggests calling it before trendyol_call_api or after trendyol_list_operations, but no when-to-use/when-not-to-use condition or alternative is spelled out. An agent must infer the position of this tool in the workflow.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description goes further by disclosing what the output contains (operationId, HTTP method, path, short description) and the scope of sections, which is valuable since no output schema exists; it does not mention size or pagination limits.

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

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

Two sentences, front-loaded with the purpose and return fields, followed by the section enumeration that scopes coverage. No filler, though the trailing category list is somewhat long.

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

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

With no output schema, the description usefully summarizes the returned fields and section scope. However, it omits how this fits the workflow relative to siblings (e.g., discover here, then get_operation/call_api) and says nothing about pagination or result size, leaving gaps for a catalog-listing tool.

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

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

Schema description coverage is 50%: the 'filter' parameter is documented in the schema but the 'type' enum (all/read/write) has no description. The tool description adds nothing about either parameter, so it fails to compensate for the half of the schema that is undocumented.

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

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

The description states a specific verb (list) and resource (all Trendyol API operations) and even enumerates the fields returned (operationId, HTTP method, path, short description) plus the covered sections. It is clearly distinguishable from get_operation or search_docs by being a full-catalog listing, though it never names a sibling to sharpen the contrast.

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

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

Usage is only implied: listing all operations by section suggests a discovery/browse entry point, but the description never states when to prefer this over trendyol_search_docs or trendyol_get_operation, nor any exclusions or prerequisites. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral detail: the scope is stores defined on this local machine, and API credentials are deliberately not returned, which tells the agent what it will and will not see. It stops short of describing ordering or empty-list 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?

Three short sentences, each earning its place: the listing action, the returned fields, the security caveat, and the follow-up workflow. The core purpose is front-loaded with no filler.

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

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

There is no output schema, so the description must carry the return-value burden, and it does by naming the four fields returned and explicitly stating that API credentials are withheld. Combined with the annotations covering the safety profile, nothing needed to call this correctly is missing.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline is 4. The description correctly does not invent parameter guidance, and instead uses the space to describe the fields the call surfaces.

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 ('Kullanıcının bu bilgisayarda tanımladığı Trendyol mağazalarını listeler') and enumerates the returned fields (ad, satıcı ID, ortam, yazma izni). It also names the sibling tool that consumes the result (trendyol_call_api), so an agent can distinguish it from the doc/operation siblings without opening a schema.

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

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

The description implies its role as a discovery step by explaining that with multiple stores the choice is made via the store parameter of trendyol_call_api, which is useful workflow context. However, it never explicitly states when to call this tool versus the sibling list tools, nor any exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavior beyond that: the return format (markdown) and the empty-slug fallback that returns a list of all guides. It does not address pagination interaction between offset/maxChars, so it stays at a solid-but-limited 3.

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

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

Three short sentences, front-loaded with the return type followed by the input format and the fallback behavior. No filler, though the fallback clause could be slightly tighter.

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

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

With no output schema, the description correctly carries the burden of explaining the return value (markdown page vs. guide list) and the input format. It is nearly complete for a read tool; only the offset/maxChars interplay for long pages is left implicit.

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

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

Schema coverage is 67%; the schema documents slug and offset, but maxChars has bounds only with no prose. The description reinforces slug semantics (slug OR full URL) and the empty-slug behavior, but adds nothing about offset or maxChars, so it does not fully compensate for the coverage gap.

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

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

States a specific verb and resource: returns a Trendyol documentation page as markdown, plus the fallback listing behavior. An agent can distinguish it from trendyol_search_docs, though the description never names that sibling explicitly to sharpen the contrast.

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 explains what to pass (slug like '2-authorization' or a full URL) and what happens if the slug is empty, which implies the listing use case. However, it never states when to prefer this over trendyol_search_docs, so the selection guidance is only implicit.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and scope are largely covered. The description does add a non-obvious behavioral trait (Turkish diacritic/character insensitivity) and confirms the corpus is its own documentation site, but says nothing about ranking, result ordering, or how hits map to the read/operation tools.

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

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

Two compact sentences, purpose front-loaded, and the example list consolidates query semantics efficiently. Slightly dense but no wasted filler.

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

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

With no output schema and three parameters, the description carries the burden of explaining what a result looks like. It never says whether hits are operation names, IDs, or snippets that feed into trendyol_read_doc / trendyol_get_operation, which is the key missing detail for a discovery tool in this toolset.

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%: 'query' and 'kind' are documented in the schema, while 'limit' (min 1, max 30, default 10) is not described anywhere. The description's mention of 'kılavuzlar' and 'API işlemleri' loosely maps to the kind enum values guide/operation, and the examples clarify what a query string should look like – useful but only marginal beyond the schema.

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

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

States a specific verb and resource: searching all guides and API operations on developers.trendyol.com. It implicitly distinguishes itself from siblings like trendyol_get_operation or trendyol_read_doc, but never names an alternative, so sibling 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 example queries ('stok fiyat güncelleme', 'iade onaylama', 'createProducts') illustrate when the tool is useful and imply the free-text nature of input. However, there is no explicit guidance on when to search versus going directly to trendyol_get_operation / trendyol_list_operations, nor any exclusions.

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