bozfix

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is clear. The description adds behavioral context beyond annotations: it emphasizes honest reporting, output categories (iyi/zayıf/henüz yok), and the directive to still proceed with weak coverage while being transparent. This enriches the tool's expected behavior without contradicting annotations.

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

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

The description is concise yet information-dense: it states the core function in the first sentence, then provides imperative usage guidance in the second, and a conditional behavioral rule in the third. Every sentence earns its place without redundancy, making it highly accessible for an AI 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?

Given the tool's moderate complexity and the absence of an output schema, the description adequately explains return categories and usage intent. It doesn't cover error handling or invalid district cases, but the openWorldHint annotation and sibling context reduce the need for exhaustive detail. Overall, it's complete enough for correct invocation and interpretation.

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 both parameters described in the schema. The description only reiterates that the category is optional and the district is required, adding no new meaning beyond what the schema already provides. Baseline 3 is appropriate since the schema carries the full semantic weight.

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: it reports how many approved craftsmen serve in a given Antalya district, with optional category filtering, and classifies coverage as good/weak/none. This is a specific verb+resource combination that distinguishes it from siblings like usta_ara (which likely searches for individual craftsmen) and fiyat_tahmini (price estimation).

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

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

The description gives explicit usage context: use it to set user expectations before making promises, and if coverage is weak, the agent may still open a request but must mention the limitation. It doesn't explicitly name alternatives or state when not to use it, but the guidance is clear and actionable.

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

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

The description adds valuable behavioral context beyond the readOnlyHint annotation: it states the price range is based on 'tamamlanmış GERÇEK işlere' (completed real jobs) and explicitly says that if there is insufficient data, it will state so clearly and not fabricate prices. This transparency about data limitations and honesty is a strong addition that helps the agent trust the output. No contradiction with annotations is present.

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 two short sentences that front-load the core purpose and immediately follow with a key behavioral guarantee. Every word serves a purpose, with no redundant or irrelevant content. It is concise yet informative.

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 carries the burden of explaining return values. It states the output is an estimated price range in TRY, but does not detail the exact format (e.g., min/max fields). Given the tool's simplicity and the strong behavioral notes, the description is mostly complete, but a little more specificity on the return structure would make it fully complete.

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

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

Schema description coverage is 100%, with both 'kategori_id' and 'ilce' already described in the schema. The description mentions 'kategori/ilçe' but does not add further semantic meaning beyond what the schema provides. Therefore a baseline score of 3 is appropriate, as the description neither compensates for missing schema info nor adds new parameter details.

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 ('döner' meaning returns) and a clear resource: estimated price range for a category/district. It clearly conveys what the tool does, but does not explicitly distinguish it from sibling tools like 'usta_ara' (find craftsman) or 'talep_durum' (request status). Despite this, the uniqueness is implied by the tool's 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?

The usage context is implied from the name and description: it is used for price estimation based on completed jobs. However, there is no explicit guidance on when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. The behavioral note that it uses 'tamamlanmış GERÇEK işlere' (completed real jobs) hints at a specific data source but does not provide decision rules.

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

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

The description adds value beyond the readOnlyHint annotation by specifying that it lists 'active' categories and that the output is intended for finding the correct category ID. It does not go into details like ordering or pagination, but for a zero-parameter list tool with readOnlyHint=true, the behavior is simple and adequately disclosed. The openWorldHint is not contradicted.

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 two sentences long, front-loaded with the main action and purpose, and includes concrete examples to illustrate the category types. Every word earns its place, with no redundant information.

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

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

For a simple, zero-parameter, read-only listing tool with no output schema, the description is complete. It states what the tool returns (active categories and their IDs), why to use it (to find correct ID before other actions), and provides examples. Sibling tools are sufficiently differentiated by the explicit mention of 'kategori id'sini bulmak'.

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 has zero parameters, so the schema fully covers parameter semantics by default. The description adds context about the return value (categories and IDs), which is relevant for using the tool. No further parameter explanation is needed.

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

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

The description clearly states that the tool lists active service categories in BOZFIX with examples (elektrikçi, tesisatçı, klima, boya...), which is specific and distinguishes it from sibling tools like usta_ara or talep_olustur. The verb 'listeler' and the resource 'aktif hizmet kategorilerini' make the purpose immediately obvious.

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 explicitly says to use it 'before searching for a master or opening a request' to find the correct category ID, providing clear when-to-use context. It does not mention when not to use or alternatives, but given no sibling tool serves the same purpose, this is acceptable. The guidance is clear and actionable.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description adds value by stating it does not return personal/customer information and that other hours 'may be available'—aligning with the openWorldHint. This manages user expectations and clarifies the data scope.

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

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

The description is compact (three sentences) yet densely informative: purpose, privacy, booking flow, and required parameters. It is front-loaded with the main function and contains no filler or redundant phrases.

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

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

With only two required parameters, read-only behavior, and no output schema, the description covers all essential aspects: what is returned, what is not returned, how to proceed for booking, and input requirements. It gives the agent enough context to invoke the tool correctly and interpret results.

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 input schema already provides full descriptions for both parameters (usta as profile slug, tarih as date format), achieving 100% coverage. The description merely restates these details without adding new constraints, examples, or edge-case information, 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 clearly states the tool returns busy hours for an approved master on a specified day, using a specific verb and resource. It distinguishes itself from the related booking tool (talep_olustur) and clarifies what it does not return (personal 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?

It explicitly directs the agent to use talep_olustur for definitive appointments, creating a clear when-to-use and when-not-to-use boundary. The context of checking availability is implied but unmistakable, and the note about approved masters sets an additional prerequisite.

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 provide readOnlyHint=true, so safety is covered. The description adds valuable behavioral context: a response only occurs when talep_no and the opening phone are both correct together, and that others' requests cannot be viewed. This goes beyond the annotations.

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

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

The description is concise (two sentences) and front-loaded with the main function, followed by a privacy warning and use case. There is no waste, though it could be marginally better structured with separators.

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

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

For a simple read-only tool with no output schema, the description covers the main aspects: what is returned (status, offer count, price range), the privacy constraint, and the intended usage context. It lacks possible status values but is otherwise complete.

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

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

The schema covers both parameters fully with descriptions. The description adds the privacy constraint that both parameters must match and clarifies that talep_no comes from talep_olustur, providing context beyond the schema.

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

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

The description states the tool 'returns the status of a previously opened request and the offer summary (how many offers, price range)' with the verb 'döner'. It clearly distinguishes itself from sibling tools like talep_olustur by focusing on querying existing requests.

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

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

The description gives an explicit use case: 'Use it to check if your newly opened request has received offers from masters'. It implies using this after talep_olustur, but it does not explicitly mention alternatives or when-not-to-use scenarios.

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?

Richly discloses critical behavioral traits beyond annotations: the request is created but not sent to artisans until user approves via a link, non-approval means no artisan sees it, and BOZFIX charges no fee. This is high-value information that annotations do not convey.

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

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

Description is somewhat long but front-loaded with purpose and each sentence carries important operational or safety detail. The warning and approval explanation are essential, so the length is justified, though it could be tightened slightly.

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

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

Given the tool's complexity, lack of output schema, and potential for misuse, the description is remarkably complete. It explains the full approval workflow, required fields, what the response should contain (onay linki), and the no-fee policy, enabling correct invocation and follow-up.

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 covers 100% of parameters, so baseline is 3. The description reinforces required parameters and mentions the onay_linki output, but does not add new semantic detail to individual parameters beyond what the schema already 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?

Description clearly states it creates a service request ('hizmet talebi açar') on the user's behalf in BOZFIX. It also distinguishes the tool by describing the approval workflow and mentioning the onay linki, setting it apart from siblings like talep_taslak_olustur.

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

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

Provides clear usage context: required fields, the need to pass the approval link to the user, and the consequence of non-approval. However, it does not explicitly mention when to use this tool versus the sibling talep_taslak_olustur, so it lacks explicit alternatives/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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description reveals critical behavioral traits: the short link does not open a request, the user must edit and approve the form, personal data must not be sent due to KVKK, and kategori_id must be real/active. It even states that it does not create fake/fabricated draft records, providing a strong safety profile.

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 dense yet well-structured. It opens with the core purpose, immediately explains the non-opening link behavior, then covers privacy and category constraints, and finally compares with the sibling tool. Every sentence adds necessary information without fluff, and key terms are front-loaded.

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

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

Given the tool's complexity (4 parameters, no output schema), the description is complete. It specifies the return format (/t/{kod}), explains the user approval flow, states privacy constraints, and clarifies the relationship with talep_olustur. No critical information is missing for an agent to select and invoke the tool 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?

The input schema already describes all four parameters, so the baseline is 3. The description adds valuable meaning by explaining that kategori_id must come from the 'kategoriler' tool and should be left blank if uncertain, and explicitly warns against sending personal data fields (ad_soyad/telefon). This goes beyond the schema, but it does not add detail for every parameter (e.g., oncelik, ilce).

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

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

The description uses a specific verb 'hazırlar' and a specific resource 'talep TASLAĞI' (request draft), and clearly states it returns a short link (/t/{kod}). It explicitly distinguishes itself from sibling 'talep_olustur' by noting the link does not open the request, making its purpose unmistakable.

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 provides explicit usage guidance: it compares with 'talep_olustur' and notes this version is safer because human approval is required. It also tells the agent what not to send (ad_soyad/telefon) and when to leave kategori_id blank, offering clear context on how to invoke the tool correctly.

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

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

Beyond the readOnlyHint annotation, the description discloses relevant behavioral traits: it sorts by score and trust score, filters to approved masters only, and explicitly states that personal contact information is not returned—only a public profile link. This adds valuable context about the tool's output and privacy characteristics beyond what annotations alone provide.

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 exceptionally concise, comprising three sentences that each serve a distinct purpose: the main action, the filtering options, and the output privacy note. It is front-loaded with the core functionality and contains no redundant or filler 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?

Given the tool's simplicity (3 optional parameters, no output schema), the description covers the essential aspects: purpose, filters, sorting, and output behavior (public profile link, no contact info). While it could elaborate on the full return structure, the note about profile links provides sufficient context for an agent to understand what to expect.

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 input schema already provides complete descriptions for all three parameters (ilce, limit, kategori_id), achieving 100% schema_description_coverage. The description's mention of 'ilce ve kategori_id ile daraltılabilir' does not add meaning beyond what the schema already conveys, so the baseline score of 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: it lists approved masters in Antalya, sorted by score and trust score. The specific verb 'listeler' (lists) and the explicit scope (ONAYLI ustalar, Antalya) make the purpose unmistakable and distinguish it from sibling tools like kategoriler or fiyat_tahmini.

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 provides contextual usage guidance by mentioning the ability to narrow results using ilce and kategori_id, and it hints at the prerequisite of obtaining category IDs from the 'kategoriler' tool. However, it does not explicitly state when to prefer this tool over others or when not to use it, so it lacks full exclusionary guidance.

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