Yazılım Koçu

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely useful context beyond that: sector metrics are representative targets rather than measured client results, which shapes how an agent should report the comparison output. It still doesn't describe the shape of the comparison response, but the annotation coverage lowers the burden.

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

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

A single front-loaded sentence covers the two modes, followed by one short caveat sentence. Every clause earns its place; the only minor cost is the dense parenthetical carrying the slug example.

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

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

There is no output schema, so the description should convey what a comparison yields, and it only hints at it via the sector-metrics caveat. For a simple two-parameter read tool with strong annotations, the omission is tolerable but leaves the agent guessing about result structure and error behavior for invalid codes or slugs.

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

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

Schema coverage is 0% and the parameters are opaque single letters, so the description carries the full burden. It partially compensates by specifying the value domain (framework code or sector slug, with an example), but it never maps the two required fields to a role or clarifies whether a and b must be the same type, leaving real ambiguity.

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 (compare) and names two concrete resource types: Yazılım Koçu frameworks identified by code, and sector solution pages identified by slug. It gives a worked example ("finans" vs "uretim"), so an agent can distinguish it from the read-only sibling tools like get_frameworks and get_page that fetch single items.

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 to use it (two items of the same kind to contrast) and how to supply identifiers (code vs slug), but it gives no explicit exclusions or prerequisites. It never says whether mixed inputs (one code, one slug) are invalid, nor does it tell the agent to call get_frameworks or list_services first to discover valid codes or slugs.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the tool has two distinct modes depending on whether tool_id is supplied, and its output is meant to be relayed to the user before scoring. It does not describe the shape of the returned question list, which keeps it from a 5.

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

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

One sentence, front-loaded with the primary list behavior, then the conditional tool_id behavior, then the downstream action. No filler or redundant restatement of the title.

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

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

For a read-only, single-optional-parameter tool with no output schema, the description covers both modes and the intended follow-up call. The only gap is that it does not hint at the structure of the returned questions/options, which an agent must handle to ask the user.

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%, but the single parameter is a fully enumerated enum that self-documents the valid assessment IDs. The description still adds meaning by explaining that tool_id switches the tool from list mode to question-retrieval mode, which the schema alone does not convey.

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 a specific verb and resource ('List Yazılım Koçu's free self-assessment tools') and explicitly covers the second mode ('given tool_id, return its questions and answer options'). It also implicitly separates this tool from score_assessment, which is named as the downstream step rather than a duplicate.

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

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

It gives a clear workflow: fetch questions, ask the user, then call score_assessment. That is strong when-to-use guidance and names the alternative tool. It stops short of stating exclusions or prerequisites (e.g. what happens with an invalid tool_id), so it is not a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, closed-world and non-destructive behavior, so the safety profile is covered. The description adds a useful hint about returned content (citation-ready definitions with canonical URLs), which matters because there is no output schema, but says nothing about result size or completeness of the 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?

A single dense sentence that front-loads the primary listing behavior and then the single-item mode, with no filler whatsoever.

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 one-optional-parameter read tool with full annotation coverage, the description covers both modes and the nature of the return content. Only minor details, such as whether the list is exhaustive or ordered, are 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?

There is one parameter with 0% schema description coverage, so the description must carry the meaning. It does explain that 'code' selects a single framework and that omitting it lists all, but gives no format or case rules for codes beyond the illustrative examples.

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

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

The description pairs specific verbs (list, return one in full) with a specific resource (published decision frameworks) and concrete examples (4VS, TBAM, 3DR). It is clear what the tool retrieves, though it does not explicitly contrast itself with siblings like get_page or search_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?

The two operating modes are implied by the phrasing: no code yields a list, a code yields one framework in full. That is enough to call the tool correctly, but there is no explicit guidance on when to prefer it over search_content or get_page for the same material.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds material context beyond that: a ~12k character truncation cap on returned content and an explicit six-domain allowlist that defines the closed world in concrete terms. Return-format disclosure is a further plus, though nothing is said about error behavior or redirects.

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

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

Two sentences, zero filler: the first covers action, source and return payload with the truncation limit; the second front-loads the hard constraint. Every clause carries information the agent needs.

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

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

For a one-parameter read tool with no output schema, the description supplies what structured fields cannot: the shape of the returned content and its size ceiling. Combined with annotations covering the safety profile, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the single url parameter is already documented as 'Full https URL on one of the six sites'. The description earns extra credit by actually enumerating the six permitted domains, which the schema only alludes to, making the constraint actionable without a trial call.

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 ('Fetch') and resource ('a page'), names the site family, and states exactly what is returned (title, description, markdown body). It stops short of explicitly contrasting with the sibling search_content, so the agent must infer the fetch-vs-search split, but the core purpose is unambiguous.

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

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

The when-not case is encoded as a domain allowlist ('Only these domains are allowed' plus the six listed hosts), which tells the agent when a call will fail. However, there is no guidance on when to prefer this over search_content or site_overview, so usage is only 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: prices are in TRY, VAT excluded, static and identical to the public website, and the model must not fabricate alternatives.

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 return content and ending on the anti-fabrication constraint. The category list is dense but each item earns its place by defining scope; 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?

For a zero-required-parameter, read-only lookup with annotations covering safety, the description supplies enough: what comes back, currency, tax treatment, and authority. With no output schema, it could have sketched the response structure slightly more concretely, but nothing critical is missing.

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

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

Schema coverage is 100% and the single enum parameter is self-documented with a default, so the baseline is 3. The description goes further by mapping the enumerated content areas to the enum's service categories (websites, e-commerce, custom software, training), clarifying what each selection yields.

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 Yazılım Koçu's published prices — and enumerates the covered categories (website, e-commerce, custom software, AI training). It does not name a sibling such as quote_website, so the boundary with quoting tools is left implicit.

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: fetch published list prices, and 'never invent other prices' establishes this as the authoritative source. There is no explicit when-to-use/when-not guidance and no routing to quote_website for a bespoke estimate, which an agent would likely need.

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

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

The annotations already declare readOnly, idempotent, closed-world and non-destructive, so safety is fully covered. The description adds genuine behavioral value by disclosing the fields returned (duration, capacity, location, price, cohort start date, registration deadline) in the absence of an output schema. It does not state whether prices or cohort dates are live or static, which is the one remaining 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?

A single front-loaded sentence that begins with the return verb and the resource, then enumerates the payload. It is dense but every clause contributes a distinct piece of returned information; only the branded name slightly lengthens the opening.

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 parameters, no output schema and a simple read-only profile, the description carries the return-value burden and does so by listing the data fields and the cohort/deadline detail. Missing only freshness or currency of the pricing and date information, which is minor for a static content 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The description correctly implies a single unfiltered fetch with no arguments.

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 leads with a specific verb and resource ('Return Yazılım Koçu's AI & production training formats') and enumerates the four formats plus the Entrepreneurship Program, so an agent knows exactly what content domain this covers. It stops short of naming how it differs from adjacent siblings like get_pricing or list_services, which also surface commercial information.

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

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

Usage is only implied: an agent can infer this is the tool for training-program questions, including cohort dates and registration deadlines. There is no explicit statement of when to prefer this over get_pricing or list_services, and no exclusions or prerequisites 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?

The annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond that: what each returned item contains and the handoff of codes into quote_website. It says nothing about result-set size or pagination behavior beyond the schema's limit default.

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 resource and record shape, then filtering, then the sibling handoff. No filler or restatement of the name.

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

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

With no output schema, the description usefully summarizes the fields of each demo record and the code handoff to quote_website. It is nearly complete for a read-only listing tool; the only gap is guidance on result volume and whether the returned set is truncated by limit.

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

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

Schema coverage is 50%, and the description names all three filters and clarifies that query is free-text sector wording. However, it does not disambiguate 'group' (fixed sector verticals like saglik, hukuk-finans) from the free-text sector 'query', which is the main ambiguity an agent would face with two similar-looking filters.

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

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

The description gives a specific verb and resource ('List ... design demos') plus scope ('live website and e-commerce'), and it describes the record shape (stable code like WS-012 / ET-007, sector, preview URL). That is enough to separate it from siblings such as get_page or quote_website 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 states the filtering modes (category, group, free-text sector query) and names a concrete downstream alternative: a website demo code can be passed to quote_website. It does not say when NOT to use this tool or how it relates to get_page for previewing a demo, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety and side-effect profile is fully covered. The description adds one useful behavioral fact beyond that — every item comes with its URL — but says nothing about result size, ordering, or whether the list is exhaustive.

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 sentence, front-loaded with the verb and resource, then packed with the concrete content categories. No filler, no repetition of the title or annotations.

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

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

For a zero-argument, read-only catalog tool with no output schema, the description is nearly complete: it tells what is returned (services, solution pages, products, tools) and that URLs accompany each. Only the absence of any routing guidance toward the more specific sibling tools leaves a small 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for 0 params applies. The mention that each entry includes a URL is the only semantic detail needed and it is present.

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 (Yazılım Koçu's services) and enumerates the catalog's contents — services, sector solution pages, products, free assessment tools — plus the fact each entry carries a URL. It overlaps conceptually with siblings like get_training_options and get_assessment without naming them, so it is clear but not sibling-differentiated.

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

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

There is no explicit when-to-use statement and no mention of alternatives. The description never tells an agent to call this first to discover URLs before get_page, nor explains why one would pick this over get_pricing, get_training_options, or get_frameworks, even though the listed categories visibly overlap with those siblings.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely new behavioral information beyond them: it discloses the return payload (VAT-excluded and VAT-included totals, delivery days, a pre-filled configurator link). It does not discuss whether add-ons can change delivery days or how the design code affects totals.

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 calculation scope front-loaded and the return value trailing. Every clause carries information; nothing is redundant with the title or 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?

There is no output schema, and the description compensates well by enumerating the returned fields. For a four-parameter, single-purpose quote tool this is nearly complete, losing only the optional design parameter and any note on how add-ons interact with delivery timing.

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

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

Schema description coverage is 100%, with both enums documented in the schema itself, so the baseline is 3. The description restates three of the four inputs at a high level but adds no format, default, or interaction semantics, and never mentions the optional 'design' parameter.

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

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

The description gives a specific verb and resource — 'Calculate the exact price of a ... corporate website' — and names the concrete inputs (package, add-ons, languages). It also states the calculation source ('same formula as the website configurator'), which separates it from a static price list. It stops short of naming the likely-confusable sibling get_pricing, so the agent must infer the boundary 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?

Usage is implied rather than stated: the agent can infer this is the tool for quoting a configured site, but there is no explicit 'use this when...' or 'do not use for...' sentence. With a sibling named get_pricing in the same family, the absence of a routing rule is a real gap.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description usefully adds what comes back (tier, explanation, recommendations) and that scoring matches the website, but says nothing about failure modes such as an unknown tool_id or a mismatched number of answers.

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 clauses with the action and inputs front-loaded and the return values in a trailing parenthetical. No filler, though the parenthetical '(same scoring as the website)' is marginally tangential.

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 one-line return summary is valuable, and the required inputs are identified. However, for a scoring tool keyed to an enum of assessment types, the description omits how to obtain valid answers, ordering/count constraints, and error behavior, leaving meaningful gaps.

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

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

Schema coverage is only 50%: tool_id has an enum but no description at all, while answers is documented. The description partially compensates by stressing 'chosen option values in question order', yet that mostly restates the answers schema text and gives no hint about where option values come from or whether answer count must match question count.

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 a specific verb and resource ('Score a free self-assessment') and states the two inputs it consumes. It is distinguishable from the sibling get_assessment (retrieve) by the scoring action, though that contrast is only implicit rather than stated.

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

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

Usage is implied through 'pass tool_id and the chosen option values in question order' and the phrase 'free self-assessment', which suggests the pre-quote stage. There is no explicit when-to-use/when-not guidance and no named alternative such as get_assessment, which likely supplies the questions and option values.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: result ordering favors the current satellite site then hub pages, and it signals that results are references to be opened with get_page rather than full 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?

Four short sentences, front-loaded with what is searched, then result ordering, then the next step, then a usage tip. Nothing is redundant with the schema and no sentence is filler.

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

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

With no output schema, the description carries the burden of explaining what comes back, and it does so indirectly by describing ordering and that results must be read via get_page. It stops short of describing result shape or how the limit interacts with result count, but the essentials for correct invocation are 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 coverage is 100%, so all three parameters are already documented, including the site/all enum. The description still adds value by showing the intended query language and giving concrete Turkish query examples, and by explaining what "site" scope actually yields (this site plus top hub pages).

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

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

The description opens with a specific verb and an enumerated resource set: "Search published articles, buyer guides, solution pages, tools and design demos." This clearly distinguishes it from sibling tools that list one content type (list_design_demos, list_services) or fetch a single page (get_page).

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

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

It gives explicit follow-up routing ("Use get_page to read a result") and explains the ordering behavior on satellite sites, which tells the agent what to expect from results. It does not, however, say when to prefer this over the list_* or get_frameworks siblings when browsing rather than searching.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds that the payload is descriptive context about the publisher and network, but says nothing about response size, shape, or whether it is static cached text. With annotations doing the heavy lifting, this is adequate rather than rich.

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

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

Two sentences, no filler, with the content scope stated before the usage directive. Every clause earns its place.

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

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

For a zero-parameter, read-only orientation tool with no output schema, the description covers what an agent needs to decide to call it. The only gap is that it does not characterize the returned content's form (e.g., a prose summary vs. structured list of network sites).

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description correctly implies a parameterless, always-available call by framing it as a general orientation step.

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

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

The description names a specific verb and a concrete set of resources: describing the website, its publisher (Yazılım Koçu), its topics, and the other sites in the network. That is far more informative than the title 'Site ve ekip tanıtımı' alone, though it never explicitly contrasts itself with siblings like get_page or list_services.

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

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

'Call this first when you need context about the site' gives a clear triggering condition and an ordering preference relative to other tools. It stops short of naming when not to use it or which sibling supersedes it for narrower lookups.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, so the description only needs to add what they cannot. It does add real value: the output is an exact form link, and there is an explicit data-handling constraint (no name/e-mail/phone in chat, KVKK consent happens on the form). It does not say what happens if the wrong 'need' value is chosen or whether the link is stable across calls.

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, trigger condition first, constraint second, with no redundant restatement of the tool name or schema. Every clause carries actionable information.

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

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

For a one-parameter, no-output-schema tool with full annotation coverage, the description supplies what an agent needs: when to fire, what is returned (a form link), and the privacy constraint. The only gap is disambiguation from siblings that also serve offer/training intents.

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 'need' parameter carries a fully enumerated 15-value list documented in the schema, so the baseline is 3. The description only echoes this with "for that need" and adds no guidance on how to pick among overlapping enum values like 'egitim' vs 'kurumsal-egitim' or 'diger'.

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 a concrete action ("return the exact Yazılım Koçu form link") plus the triggering needs (offer, meeting, project, training), which is far more specific than the title alone. It does not explicitly contrast itself with overlapping siblings such as quote_website or get_training_options, so an agent must infer the boundary between requesting a link and getting pricing/training details.

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?

Trigger conditions are stated clearly ("When the user wants an offer, a meeting or to start a project or training"), and a negative rule is included ("Do NOT collect personal data ... in the chat"). It stops short of naming which sibling tool to use for adjacent intents, so the when-not guidance is partial.

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