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

Beyond the readOnlyHint annotation, the description discloses extensive behavioral details: validation checks (XML format, OASIS UBL 2.1 XSD, GİB e-Fatura schematron with 498 rules, arithmetic, signature), and the structure of findings (code, level, original message, line number, Turkish explanation and correction). This goes well beyond 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 dense and front-loaded with the main purpose, followed by useful details. It is slightly redundant because the English sentence at the end restates the Turkish opening, but the overall structure is efficient and scannable.

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 three parameters and no schema descriptions, the description covers input selection, type auto-detection, the full validation scope, and output finding structure. An output schema exists, so return handling is already defined; the description still adds useful context, making it complete enough 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?

With 0% schema description coverage, the description compensates fully by explaining the meaning of `dosya` (local path), `xml` (document text), and `tur` (enumerated values and auto-detection from root/ProfileID if omitted). It adds substantial 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 clearly states the tool 'denetler' (audits) a UBL-TR document and later explicitly says 'Validates a Turkish UBL-TR e-invoice with the tax authority's own schematron and returns findings.' This is a specific verb-resource pair that distinguishes it from siblings like belge_ozeti (summary) or bulgu_acikla (finding explanation).

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 makes the usage context clear: it is for validation of UBL-TR documents. It explains how to provide input (dosya or xml) and how tur is determined. However, it does not explicitly mention alternatives or when not to use it, so it lacks exclusions but is still clear.

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

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

The description discloses a concrete behavioral limitation: only the first 50 lines are included ('satırlar (ilk 50)'), and it mentions a signature flag ('imzalı mı'). This goes beyond the readOnlyHint annotation. However, it says nothing about error handling, parameter precedence, or the relationship between the two input options.

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 it has redundant halves: the Turkish list and the English summary largely overlap. The key behavioral detail (50-line limit) is buried in the Turkish portion rather than front-loaded in the summary 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?

An output schema exists, so return structure is covered elsewhere, but the input side is crucial and unexplained. An agent has no way to know what to pass for 'xml' or 'dosya', nor when this particular summary tool is the right choice relative to its 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 0%, and the tool description never mentions 'xml' or 'dosya', so an agent gains no extra meaning about input format, expected structure, or whether the parameters are alternatives. The parameter names are mildly self-explanatory but insufficient for confident invocation.

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 'Summary of a UBL-TR document' and enumerates the output components (parties, lines, taxes, totals, signature flag), which is a specific resource-verb pair. It does not explicitly distinguish itself from siblings like 'belge_dogrula' or 'bulgu_acikla', but the summary/validate/explain distinction is reasonably 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?

There is no guidance on when to use this tool versus the sibling validation/explanation tools, and no indication of whether to pass XML content via 'xml' or a file path via 'dosya'. The description does not mention prerequisites, mutual exclusivity of the two parameters, or what happens if neither is supplied.

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, so the description's content is consistent. It adds behavioral detail about the output (which field was rejected, why, how to fix) and notes the explanation is in Turkish, which is valuable beyond 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, with two sentences. The English sentence 'Explains a finding code' is a redundant translation of the Turkish, but it does not add unnecessary length. The main information is front-loaded.

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

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

For a single-parameter read-only tool, the description is fairly complete: it explains the purpose, the input, and the output content. The output schema likely covers return structure, so this is 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?

The schema provides no parameter description (0% coverage). The description compensates by identifying the parameter as a finding code and giving examples like 'sch-GeneralUnitCodeCheck-1' and 'hesap-dip-odenecek', clarifying the expected input.

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 explains a finding code, providing the Turkish explanation, the rejected field, reason, and fix. It includes concrete code examples, distinguishing it from sibling tools that handle documents (belge_ozeti, belge_dogrula) rather than findings.

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 you need to explain a finding code. However, it does not explicitly mention alternatives or when not to use this tool, leaving differentiation to 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the content scope (available lists, versions) but no additional behavioral details such as ordering, pagination, or failure behavior; it does not contradict 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 short and front-loaded with the main purpose. The bilingual repetition is somewhat redundant, but it is compact and serves a multilingual audience.

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 parameterless read-only tool with an output schema present, the description covers the essential information: what is returned and the scope ('available'). No prerequisites, permissions, or side effects are relevant, and the read-only annotation covers the safety profile.

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 and the schema is an empty object, so there is nothing to document. The baseline for a 0-parameter tool is 4, and the description appropriately focuses on the output rather than inputs.

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 specifies a concrete output: names and Turkish descriptions of available GİB code lists plus package versions. It is not a tautology and the plural scope distinguishes it from the sibling kod_listesi, though it lacks an explicit verb like 'returns' or 'lists'.

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 use case is implied: call when you need an inventory of available code lists or build/package versions. No explicit when-to-use/when-not-to-use guidance or mention of the sibling kod_listesi 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?

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds meaningful context: it specifies the values are 'as enforced by the schematron' (şematronun fiilen uyguladığı liste), clarifying the authoritative source. It also provides a list of example list names, giving insight into valid inputs. No contradiction with 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 relatively concise, using a colon and a list of examples. It is front-loaded with the core purpose. The list of examples is somewhat lengthy but adds value by indicating valid inputs. No wasted sentences.

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

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

There is an output schema, so return format is covered. However, the description does not explain how to use the 'liste' parameter, what values are valid beyond the given examples, or how the 'ara' filter interacts. Sibling differentiation is also missing. The tool is not fully self-contained for an agent.

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% – the description does not explain the 'liste' parameter at all. It does mention 'ara' as a substring filter, but does not describe its format or behavior. The example list names partially hint at valid 'liste' values, but the description fails to explicitly define either parameter. Given zero schema coverage, the description insufficiently compensates.

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 values of a GİB code list and lists example list names (UnitCodeList, TaxType, etc.). It is clear that the tool retrieves code values for a specified list. However, it does not explicitly differentiate from the sibling 'kod_listeleri' which likely lists available code lists, though the name and examples imply this.

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 explicit guidance on when to use this tool versus the sibling 'kod_listeleri'. The description mentions the 'ara' substring filter, which hints at usage, but there is no statement of conditions or alternatives. An agent is left to infer when to use this tool.

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