Temsor API — Turkey & EU business data

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

With no annotations, the description carries the full burden. It discloses all verification checks (syntax, domain mail exchanger, disposable, role, typo) and normalization, and explicitly states the absence of SMTP probing. It does not cover authentication needs or rate limits, but provides sufficient behavioral details.

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 informative but slightly verbose. It front-loads the main purpose and then explains the rationale. Every sentence adds value, though some trimming could improve conciseness.

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

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

Given the 3 parameters, no output schema, and no annotations, the description provides a good level of context about what the tool does and its methodology. It lacks details on output format and error handling, but is reasonably complete for a verification 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 low (33%), so the description must compensate. It explains the 'email' parameter by detailing the checks performed, but does not explicitly link the boolean parameters 'rejectRoleAccounts' and 'rejectFreeProviders' to their functions, though 'role-account detection' and 'disposable service' are mentioned. Adds some value but could be more explicit.

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 clear verb ('checks') and resource ('e-mail address'), and lists multiple verification aspects (syntax, domain mail receipt, disposable detection, role detection, typo correction, normalization). It distinguishes itself from competitors by explicitly stating what is not done (no SMTP probing).

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 explains what the tool does and does not do, and provides reasoning for its approach. It implicitly suggests when to use it (when reliable verification without SMTP probing is needed) but does not explicitly mention alternative sibling tools or when not to use it.

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

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

With no annotations, the description carries the full behavioral burden. It explains how the tool differs from mod-97-only validators, that it checks BBAN structure, that corrected check digits are suggested, and that bankName can be null. A slight internal inconsistency exists between 'bank and branch codes' and the later explanation only mentioning bankName, but overall behavior is well disclosed.

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 and front-loaded with the core action. Each subsequent sentence adds meaningful information — why stronger validation matters, correction behavior, bank-name limitations, and what the tool is not. No wasted words or repetition.

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 that there is no output schema, the description compensates by explaining corrective suggestions, null bankName values, and country-specific resolution. It could be more explicit about the exact return fields, but the key behavioral context is present and sufficient for an agent to select and interpret 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?

Both parameters (iban and expectCountry) are fully described in the input schema, so the description's lack of extra parameter-level detail is acceptable. It adds no new semantic or syntax information beyond schema coverage, earning the baseline 3.

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

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

Opening sentence clearly states the tool's purpose: 'Validates an IBAN from any of 70+ countries: checksum, country length and in-country account structure, and resolves the bank and branch codes.' This names a specific verb, resource, and scope, distinguishing it from the many sibling validation tools by focusing exclusively on IBANs.

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 clear context about when this tool exceeds basic checksum validation and warns against interpreting it as a SWIFT directory. It does not explicitly name alternative tools or state 'when not to use', but the limitations and unique added value are clearly 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?

With no annotations, the description carries the disclosure burden. It reveals that the service stores a pointer rather than full media ('Temsor keeps a pointer') and that STT processing only occurs during active calls, which is useful side-effect information. It omits other behavioral details such as persistence/retention, idempotency, or what happens to previously notified chunks.

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 definition is short and front-loaded, with the core operation in the first clause and key preference/behavior in the following sentences. The parenthetical 'idle $0' is cryptic and unexplained, which slightly reduces clarity, but there is 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 five-parameter tool with no annotations and no output schema, the description is too sparse. It fails to define t_ms and pbx_id semantics, doesn't explain what response or acknowledgement to expect, and leaves 'idle $0' ambiguous, so an agent cannot fully determine 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?

Only uri and bytes_b64 have schema descriptions; context signals put schema coverage at 40%. The description reinforces that a customer URI is preferred and that bytes_b64 is a demo fallback, but t_ms and pbx_id are left completely unexplained, and call_id is only implied. Low schema coverage means the description needed to compensate for these gaps and did not.

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 ('Notify') and names the resource ('optional audio chunk / customer URI') for a live or archived PBX call. It does not explicitly distinguish itself from PBX siblings like pbx_events or pbx_register, but the audio-focused resource makes the scope reasonably clear.

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 preferred input mode ('Prefer customer storage URI') and a key temporal constraint ('STT only while a call is active'), giving an agent context for when the operation is meaningful. It does not name alternative tools or explicitly state when not to use this one, so usage guidance is clear but not exhaustive.

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

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

With no annotations, the description must carry behavioral transparency. It indicates a GET request and scoping, but 'Idle $0' and 'No DID sales' are cryptic and do not clarify side effects, costs, or rate limits.

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

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

The description is short but includes confusing, seemingly unrelated phrases such as 'Idle $0' and 'No DID sales'. These extra fragments reduce clarity and make the description less focused than it should be.

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

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

The description lacks important context such as expected response format, pagination behavior, or relationship to sibling call-related tools. The unclear phrases do not fill these gaps and may mislead 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?

The only parameter, limit, is fully described in the schema with range 1-100 and a default of 20. The description repeats the limit but adds no new semantic meaning, so the baseline score applies.

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

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

The description states that the tool lists recent calls and includes transfer path crumbs, and gives an endpoint. However, phrases like 'site + customer archive browser', 'Idle $0', and 'No DID sales' are unclear and obscure the core 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 description mentions scoping by 'x-temsor-pbx-key' but does not explain when to use this tool instead of related tools like pbx_calls_get, pbx_calls_graph, or pbx_search. No usage conditions or alternative selection guidance is provided.

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

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

With no annotations, the description carries the full burden. It discloses the scoping header, the found=false behavior for missing IDs, and an 'Idle $0' note (likely cost-related). It does not mention error handling, side effects, or rate limits, leaving some behavioral aspects opaque.

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 and directly worded, using telegraphic style. It conveys the essential points without fluff. The phrase 'Idle $0' is slightly cryptic and could be clarified, but overall the structure is efficient.

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

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

Without an output schema, the description should clarify the return structure. It mentions found=false when missing but does not describe the transfer graph payload, potential error codes, or pagination. This leaves gaps for an agent needing to handle the response 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 sole parameter call_id is well-documented in the schema with a clear description and example (call_msp_002), and the tool description reinforces its purpose. This exceeds the baseline since the example aids usage, though no additional context about ID format beyond the schema is given.

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: retrieving a single call by ID along with its transfer graph, and mentions the customer detail drawer use case. This distinguishes it from sibling tools like pbx_calls (likely list) and pbx_calls_graph (graph-only), so the 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 description implies when to use this tool (when a single call with transfer graph is needed, e.g., for a customer detail drawer) and provides practical details like scoping by x-temsor-pbx-key and the found=false behavior when missing. However, it does not explicitly contrast with alternatives, though this is largely inferable from the name and purpose.

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

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

No annotations are provided, so the description carries the full transparency burden. It discloses the GET method, the endpoint format, the response structure, the localized path_tr field, the idle cost ('Idle $0'), and boundary conditions ('No DID sales / no live PSTN'). It does not cover authentication, rate limits, or error behavior, but it provides substantially more behavioral context than a generic read-tool description.

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

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

The description is short and front-loads the main concept, which is good. But the phrase 'Idle $0.' appears twice, and marketing language like 'moat' and 'compounding asset' adds noise without helping an agent act. It is concise but not perfectly economical.

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 two-parameter read tool with no output schema, the description supplies essential context: the HTTP method, query parameters, the names of returned fields, the plain-Turkish variant, and the search/orchestration use case. It does not deeply define what path or edges mean semantically, but the 'who→whom→where' framing covers the core meaning well enough.

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

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

Schema description coverage is 100%, and both call_id and stuck_at already have meaningful schema descriptions. The description only restates them in endpoint shorthand ('call_id=…&stuck_at=310') without adding new semantic detail. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description names a concrete resource ('Handoff graph + transfer edges') and explicitly states the HTTP endpoint and return fields ('Returns path, path_tr, edges, and raw transfers'). It also distinguishes itself from transcript-style tools by saying 'handoff edges, not a bot transcript,' which helps an agent separate it from siblings like pbx_calls or pbx_search. The 'moat' jargon is decorative, but the core purpose is 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 gives a clear use context: 'Compounding asset for search/orchestration' and explicitly contrasts with 'not a bot transcript.' That conveys when to reach for this tool versus a transcript-oriented tool. However, it never names specific sibling tools or states when NOT to use it in favor of pbx_calls_get or pbx_search, so the guidance is contextual rather than fully explicit.

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

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

With no annotations, the description carries the full burden but only partially discharges it. It usefully discloses cost/latency behavior ('Idle $0, no LLM'), tenant scoping, and that it is a GET read, but says nothing about auth requirements, rate limits, or whether the dictionary is cached/static.

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

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

It is reasonably short and the retrieval mechanics are front-loaded, but the first sentence is dense with unexplained internal jargon ('E4', 'example packs thicken per pilot', 'No invented premiums') that consumes space without informing an agent. Several phrases do not earn their place.

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

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

There is no output schema, so the description should convey the return shape. It indicates the payload is synonyms/aliases feeding search and Fact extraction, but never describes the structure or size of the returned dictionary, leaving a gap for a read tool with no output contract.

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 already 100% for the single enum parameter, so a baseline of 3 applies. The description adds real meaning beyond the schema by clarifying that 'msp' is a legacy alias for 'santral_firmasi', which the schema enum alone does not explain.

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

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

The description identifies the resource (a managed SaaS domain dictionary of tenant-scoped aliases) and its downstream use (boosting search and transcript Fact extraction), which lets an agent distinguish it from the many validation/lookup siblings. The verb is implicit (it is a GET retrieval) and the opening line is muddied by internal jargon like 'E4' and 'example packs thicken per pilot', so clarity is good but not crisp.

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 hints at the alternative write path by naming 'POST /v1/pbx/dictionary/add' (the pbx_dictionary_add sibling), which gives partial routing guidance. However, it never states when an agent should fetch the dictionary versus relying on pbx_search or pbx_facts directly, so usage is only 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?

With no annotations, the description must carry the behavioral burden, and it does disclose real traits: a rate limit of 60/hour/key returning 429, idle cost of $0, no LLM involvement, and scope resolution based on whether an x-temsor-pbx-key is registered. However, it omits what happens on duplicate/conflicting aliases, whether adds are reversible, and the auth requirement itself is only implied.

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 paragraphs with heavy repetition — the endpoint and the E4/compounding/'no invented premiums' phrasing appear twice, and 'Managed SaaS compounding (E4): tenant-scoped aliases thicken search + fact extract' duplicates the first sentence. Marketing language crowds out the operational facts.

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

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

For an 8-parameter mutation tool with no output schema and no annotations, the description covers rate limits, scope resolution, domain legacy mapping, and cost, which is more than minimal. But it is silent on response shape, duplicate handling, and error behavior beyond the 429, leaving gaps for a write operation.

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

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

Schema coverage is 75%, so the schema already documents most parameters, making 3 the baseline. The description mostly restates the enum values the schema already carries and is even narrower for domain (omits msp), adding little new meaning beyond the schema's own descriptions.

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 opening states a specific verb and resource ('Add a synonym/alias') and scopes it ('tenant-scoped or global demo'), so an agent can identify the operation. It does not explicitly differentiate itself from the sibling pbx_dictionary (presumably the read counterpart), and the marketing noise around it dilutes the signal, 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?

No statement of when to use this versus pbx_dictionary, pbx_search, or pbx_facts. Usage is only inferable from the tool name. The description gives conditions like rate limits but never says 'use this when you need to register a new alias'.

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?

Since no annotations are provided, the description must disclose all behavioral traits. It covers key aspects: optional HMAC authentication with detailed signature format, idle cost of $0, body size limit (256 KiB → 429), and the heuristic (no LLM) for promise extraction. It also notes that demo stores events in memory/file. This is comprehensive for a tool with no annotations, though it could mention persistence guarantees for production.

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

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

The description is a single dense paragraph with multiple sentences, but each sentence adds distinct information: purpose, authentication, event handling, cost, limits, and advanced use. It is front-loaded with the core purpose and then details. Slightly long but each part is relevant; no fluff detected. The use of 'Advanced:' clearly separates optional context.

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 (2 params, batch events, multiple behaviors), the description covers essential aspects: purpose, authentication, limits, and processing logic. No output schema means the description should hint at return values, but it doesn't, which is a minor gap. However, for a tool with no annotations, it is sufficiently complete for an agent to invoke 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%, so the input schema already describes both parameters. The description adds context that the 'events' parameter contains utterance/text fields that trigger heuristic extraction, which goes slightly beyond the schema's 'trigger heuristic promise extract' but not significantly. For pbx_id, the description doesn't add much beyond its name and schema. Baseline 3 is appropriate because the schema does the heavy lifting, and the description adds marginal value.

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 ingests call-ops events to create promises and transfer crumbs, with a specific verb ('Ingest') and resource ('call-ops events'). It distinguishes itself from siblings like pbx_ingest_transcript and pbx_calls by focusing on raw event batches for search/orchestration. However, it could be more explicit about how it differs from pbx_ingest_transcript, but the core purpose is clear.

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 implicit usage context: it's for ingesting events from a PBX, especially for building promise docs and transfer crumbs. It mentions advanced use case (ARI/Stasis batch) for customers running their own PBX, which guides when to use. It doesn't explicitly say when not to use or name alternatives, but the context is sufficient for a clear use case.

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

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

With no annotations, the description carries the full burden. It adds useful context: facts come from transcript extract + domain dictionary, persist in pbx-index, scoped by x-temsor-pbx-key, and mentions constraints like 'Idle $0', 'No DID sales', and 'KVKK forget ready'. However, it does not explicitly state whether the operation is read-only, does not describe error behavior, rate limits, or side effects. This is moderate transparency but not comprehensive.

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 front-loaded with purpose and filtering, then includes an API endpoint and several contextual statements. While not overly long, it contains potentially extraneous notes (e.g., 'Idle $0', 'No DID sales', 'KVKK forget ready') that may not be essential for tool selection. Every sentence adds some context, but the structure could be 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?

Given no output schema, the description does not explain the return format of the facts list, pagination details beyond the limit parameter, or error handling. It does cover the source of facts (transcript extract + dictionary), persistence, and scoping, which are helpful. However, for a tool with 5 optional parameters and no output schema, more detail on what constitutes a 'fact' and how results are ordered would improve completeness.

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 100% of parameters with descriptions, so the baseline is 3. The description adds little beyond what the schema already provides; it mentions 'filter by call_id, kind, domain, q' but does not elaborate on syntax or special values beyond the example URL that shows domain enum options. This is consistent with the baseline.

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 a specific verb ('List') and resource ('extracted facts'), and explicitly mentions the filtering dimensions (call_id, kind, domain, q). This distinguishes it from the sibling pbx_facts_get (which likely retrieves a single fact) and other pbx_* tools. The inclusion of an example API endpoint further clarifies the intent.

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 guidance on when to use this tool versus alternatives such as pbx_facts_get or pbx_search. The description mentions filtering capabilities but does not state when a list operation is preferred over a get or search. It relies on the agent inferring the use case from 'List', which is weak.

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

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

With no annotations, the description carries the behavioral burden and discloses important behavior: scoping by x-temsor-pbx-key, found=false if missing, and a cost hint of Idle $0. It does not explicitly state read-only behavior or full response/error semantics, but the core behavior is covered.

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 very short and scannable, covering purpose, API path, scope, and missing behavior in a few lines. Some cryptic clauses like 'Idle $0' and 'No DID sales' may be confusing but do not add significant bloat.

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-parameter get operation with no output schema, the description is reasonably complete: it includes purpose, endpoint path, authentication scope, and missing-entity behavior. It lacks explicit response shape and alternative-selection guidance, but the tool's simplicity reduces the need for more.

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 only parameter, id, is already fully described in the schema as 'Fact id (e.g. fact_001)' with min/max length. The description merely confirms retrieval 'by id' and adds no meaningful parameter semantics 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 clearly states 'Get one extracted fact by id', which is a specific verb and resource. It distinguishes this from sibling tools like pbx_facts (likely listing facts) and pbx_calls_get by focusing on a single extracted fact via id.

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 indicates this is for retrieving one fact by id and notes 'found=false if missing', which helps the agent know when to use it. However, it does not explicitly contrast with pbx_facts or pbx_search, and phrases like 'No DID sales' are ambiguous.

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

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

With no annotations, the description carries the full burden and does deliver real behavioral facts: rate limit '≤600/hour/key → 429', latency target '≤400ms whisper', idle cost '$0', and the constraint that the tool performs no STT/LLM. It omits auth requirements, idempotency of repeat upserts, and what happens if the call is already ended, so it falls short of 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?

The core purpose is front-loaded in the first clause, which is good, but the body is a run of semicolon-joined fragments ('Path to ≤400ms whisper', 'Managed SaaS in-call index; no DID sales', 'Own PBX optional footnote') that are hard to parse. Little is wasted in length, but several fragments are marketing noise rather than instruction.

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 streaming, 9-parameter, live-call state mutation with no annotations and no output schema, the description covers context, rate limits, and cost but never describes the response shape or error semantics an agent would need after calling it. Since no output schema exists, adding return-value guidance would have been valuable and is 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?

The signature line enumerates most parameters (call_id, text, speaker, t_ms, is_final, live, end_call, promote) but adds no meaning beyond the names, and pbx_id is not mentioned at all. With schema description coverage at 67%, the schema already documents several params, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('Upsert mid-call partial index') and what the input maps to ('utterances → fact/promise hints'), so an agent knows it accumulates hints from caller-posted text. It distinguishes itself reasonably from siblings like pbx_index_partial_get and pbx_ingest_transcript via 'customer posts text' and 'live call'. The telegraphic rate-limit and marketing fragments dilute an otherwise clear statement, keeping it below 5.

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

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

'While the call is live' plus 'No Temsor STT/LLM — customer posts text' implies the intended operating context and contrasts with ingest-style tools. However, no alternative tool is named explicitly and no when-not-to-use condition is given, so the routing guidance is only 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?

With no annotations, the description carries the full behavioral burden. It discloses latency target (≤400ms), cost model (idle $0), and scope (managed SaaS, no DID sales), but omits auth requirements, error behavior, and return format. Clauses like "no DID sales" and "Own PBX optional footnote" are cryptic and add little behavioral value.

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 purpose is front-loaded in the first sentence, and the overall text is short. However, the endpoint URL is somewhat redundant, and trailing clauses such as "no DID sales" and "Own PBX optional footnote" do not earn their place and make the structure feel fragmented.

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 tool with one required parameter and no output schema, the description gives enough to know it reads a live partial index for a call. Yet with no annotations and no output schema, it should say more about return structure and error conditions to be 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%, so the single call_id parameter is already fully documented in the schema. The description repeats the query parameter in a URL template but adds no syntax, format, or edge-case meaning beyond what the schema provides, so 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 and resource ("GET mid-call partial index") and clarifies the content ("accumulating facts/promises/snippets while live"). It does not explicitly differentiate from sibling tools like pbx_index_partial or pbx_facts_get, so it falls short of a 5.

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

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

Implies usage context with "for whisper ≤400ms path" and "while live," and hints at cost with "Idle $0 when no live call." However, it never states when not to use this tool or names alternative siblings, leaving alternatives 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?

No annotations are provided, so the description carries the burden. It discloses that the tool is heuristic, that it can create Promise docs with status=open, and that persist_promises=false avoids writing. It also lists example trigger words. However, it does not disclose failure modes, confidence levels, idempotency, or what happens to duplicate promises, which are relevant for a heuristic extractor.

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 and front-loaded with the core purpose, then adds the key behavioral option and integration note. The example trigger words are useful but slightly noisy. Overall, every sentence earns its place, though the structure could be tightened.

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 6 parameters, no output schema, and no annotations, the description gives the essential purpose and the most important flag, but it omits context about the optional parameters and the shape of the created Promise docs. An agent could call it correctly for the basic case, but would be guessing about the optional metadata fields and the exact return value.

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 only 33%, so the description must compensate. It explains the transcript parameter's role and the persist_promises flag's dry-run behavior, which adds meaning beyond the schema. However, it does not clarify the ext, who, pbx_id, or call_id parameters, leaving their purpose to inference. The description adds some value but does not fully cover the parameter semantics 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?

The description states a specific verb and resource: 'extracts promise-like sentences from transcript text' and 'creates open Promise docs'. It distinguishes itself from siblings by noting it is wired via utterance text on POST /v1/pbx/events, which helps differentiate it from other pbx_* tools. However, it does not explicitly name a sibling alternative, so it falls short of full differentiation.

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: use this tool when you have transcript text and want to detect promises, optionally persisting them. It mentions the persist_promises=false dry-run option, which gives some conditional guidance. It does not explicitly state when not to use it or name alternatives among the many pbx_* siblings, so usage guidance is only partially developed.

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 useful behavioral context beyond a bare endpoint: it mentions durable rows from pbx-index, derived ext_NNN identities from Transfer edges, scoping by x-temsor-pbx-key, and privacy/cost hints like 'KVKK forget ready' and 'Idle $0'. However, it omits pagination behavior, response shape, and error or edge-case details, which matter because no annotations exist.

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 mixes a product slogan ('Light CRM from call graph / facts'), endpoint syntax, implementation details, and business statements like 'No DID sales' and 'Advanced: own PBX/Asterisk stays on customer.' The key invocation information is buried and the phrasing is telegraphic, so the structure does not support quick comprehension.

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 no annotations, the description carries the full burden of explaining what the agent will receive. It does not describe the response structure, field names, count behavior, or pagination, and it fails to mention include_extensions as a parameter. The data-source and scoping details are useful but not sufficient for a complete call decision.

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 the schema already documents all parameters well. The description's inline endpoint restates q, kind, limit, and call_id without adding meaning beyond the schema, and it omits include_extensions entirely. This does not exceed the baseline expected when schema descriptions are complete.

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 identifies the resource as PBX persons and communicates that it returns caller phone/name data plus derived extension identities. It is more specific than a tautology but does not explicitly differentiate itself from the sibling pbx_persons_get, so it stops short of a 5.

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

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

The description offers no direct guidance on when to use this tool instead of alternatives such as pbx_calls, pbx_facts, pbx_persons_get, or pbx_search. There is no 'use this when...' or 'for X use...' statement, leaving the agent to infer the intended use from the endpoint.

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

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

No annotations are present, so the description carries the transparency burden. It discloses the scoping header, the found=false behavior for missing IDs, and mentions cost/idle aspects, but does not explain side effects, detailed authentication requirements, or error behavior beyond missing identities.

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 core purpose. The added notes about scoping and found=false are relevant, though phrases like 'Idle $0' and 'No DID sales' are somewhat cryptic but do not bloat the text.

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 get operation, the description is mostly complete: it identifies the resource, the parameter, and the missing-id behavior. However, there is no output schema and no description of returned fields, pagination, or error conditions other than found=false, leaving some context 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?

The only parameter, id, is well described in both the schema and the description with format examples (per_001 or ext_101). Since schema coverage is 100%, the description adds useful examples and reinforces the dual ID types.

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 gets one light-CRM identity by ID, with concrete examples of valid IDs (per_001, ext_101) and an explicit endpoint. This distinguishes it from sibling tools like pbx_persons (likely listing) and pbx_calls_get.

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 single-identity retrieval via the endpoint and example, but does not explicitly state when to prefer this over pbx_persons or pbx_search. It provides some behavioral conditions (found=false if missing) and scoping info, but lacks clear when-to-use/when-not-to-use guidance.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses the GET endpoint, scoping via 'x-temsor-pbx-key,' the 'No live PSTN' constraint, and the fact that it returns 'transfer/handoff path for orchestration.' It stops short of explicitly stating read-only/no side effects, but the GET method and listing verb strongly imply it.

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, but 'Idle $0' appears twice, which is redundant. The three sentences are otherwise efficient, yet the repetition and slightly scattered placement of context ('hotel / MSP sales demo' vs endpoint info) make the structure less polished than it could be.

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 low complexity (one optional enum parameter, no output schema, no annotations), the description provides enough to call it correctly: the endpoint, query parameter, scoping header, and the type of data returned. It does not enumerate response fields, but for a simple listing endpoint this is a minor gap.

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

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

Schema description coverage is 100%: the single 'status' parameter already has a precise enum, default, and explanation. The description's mention of 'status=open' and 'open/unclosed promises' mostly restates the schema, adding little semantic value beyond what the structured definition 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?

The description opens with a specific verb and resource: 'List open/broken call promises for agent handoff tracking.' This clearly distinguishes it from sibling mutation tools like pbx_promises_close, pbx_promises_reopen, and pbx_promises_act, all of which imply actions rather than reads.

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 states the intended use case ('agent handoff tracking — hotel / MSP sales demo') and indicates that status=open is the relevant filter for orchestration. It does not explicitly exclude alternatives or mention when to prefer close/reopen/export, but the read-only listing intent is clear enough for an agent to select this tool appropriately.

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

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

With no annotations provided, the description carries the full behavioral burden, and it delivers: it discloses rate limits (120/hour/key), shared bucket behavior, idle cost, PSTN constraints, cross-tenant isolation, and the fact that the tool records intent rather than executing live calls. This is far more transparent than the bare endpoint name.

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

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

The description packs in useful detail, but it is cluttered with redundant phrases ('Idle $0' appears twice), jargon ('E1 moat'), and repeated 'own PBX optional footnote' ideas. The key behavioral facts are present but not as cleanly organized as they could be.

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 there is no output schema and no annotations, the description provides a strong operational picture: endpoint, request shape, core behavior, rate limits, cost model, and runtime constraints. It does not describe the response format or authentication expectations, but it is otherwise reasonably complete for an invokable 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 only 50%, so the description needed to compensate. It does add meaning for the core inputs (promise_id and action) and mentions the suggested action set, but it leaves pbx_id, agent_ext, skip_forward, and stasis_webhook_url mostly unexplained. This is adequate for the main required parameter but incomplete across all six parameters.

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

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

The description clearly states the tool's verb and resource: it loads a promise and call graph, suggests whisper/transfer/hold, and records orchestra intent for agent handoff. It is specific enough to distinguish from a generic promise tool, though it does not explicitly differentiate itself from closely related siblings like pbx_orchestra_act or pbx_whisper_suggest.

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 context is implied through the description: use it when a promise's call graph should be converted into orchestra handoff intent. It offers some constraints (no live PSTN, managed SaaS, no cross-tenant merge) but does not explicitly state when to prefer this tool over related siblings or list 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?

With no annotations, the description carries the transparency burden and covers multiple behavioral traits: a 60/hour rate limit returning 429, KVKK-safe scrubbing of phones/emails in the note, scoping by x-temsor-pbx-key when set, idle pricing, and the exact POST endpoint. It stops short of stating irreversible side effects or what happens if the promise is already closed, but it is substantially transparent.

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 but efficient: a one-line action statement, the exact request shape, and key operational constraints. No sentence is redundant, and the core action is front-loaded before cost and endpoint details.

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

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

For a three-parameter mutation with 100% schema coverage and no output schema, the description supplies the endpoint, required body, scrubbing behavior, rate limit, scoping, and cost. It is missing only explicit preconditions (e.g., promise must exist and be open) and non-429 error behavior, which keeps it just short of 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%, so the schema already defines promise_id, status values, and note constraints. The description adds the endpoint body format and reiterates that the note is scrubbed, but does not materially enrich parameter semantics beyond what the schema provides.

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

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

The description opens with a specific verb and resource: 'Mark an open promise kept or broken' with an optional note. It also positions the tool as the writable counterpart to the read-only PBX tools ('makes the sales demo writable, not read-only'), which distinguishes it from siblings like pbx_promises and pbx_calls.

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 this is the write/close operation for open promises and is not for read-only queries, but it never explicitly names alternatives or states when not to use it (e.g., reopening with pbx_promises_reopen). The 'writable, not read-only' phrasing gives context, but there are no clear exclusion conditions.

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

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

With no annotations, the description carries the behavioral burden. It discloses the HTTP method (GET), filter and format usage, response fields (closed_at, close_note, path crumbs), scoping via an API key header, and even idle cost. It does not mention pagination or error handling, but it offers good transparency for a simple export operation.

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

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

The description is compact and front-loaded, stating the purpose first and then providing endpoint and behavioral details. It avoids fluff and quickly conveys the essential call. Minor ambiguity like 'Idle $0' and 'open/broken' could be tighter, but overall it is well-structured and concise.

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 no annotations and no output schema, the description provides meaningful response field and scoping details that go beyond the bare schema. However, it misses pagination, error handling, and the full status value set is only implied; the term 'open/broken' and the configuration key are under-specified. This is adequate but has notable gaps for an unannotated 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 input schema has 100% description coverage for both parameters, so a baseline of 3 is appropriate. The description adds an example endpoint and response fields, but it actually narrows the status enum to open|closed and does not add strong semantic meaning beyond the schema's own parameter descriptions. It does not compensate with extra parameter context that would exceed the baseline.

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 clear verb and resource ('Export open/broken promises') and includes endpoint details. However, the phrase 'open/broken' is ambiguous relative to the schema's broader status enum (open, kept, broken, unknown, all, closed), and it does not explicitly differentiate this tool from the sibling pbx_promises list tool, leaving some room for confusion.

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 no guidance on when to use this export tool versus the pbx_promises or pbx_promises_close/reopen siblings. It covers the how-to via endpoint example but does not state when this tool is preferable or when alternatives are appropriate. No exclusions or alternative routing are mentioned.

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

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

With no annotations, the description carries the full burden, and it delivers: it discloses the state transition, side effects (clears closed_at/close_note), scoping via x-temsor-pbx-key, rate limiting (≤60/hour/key → 429), and cost (Idle $0). This is strong behavioral disclosure for a mutating endpoint.

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

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

The description is compact and front-loaded with the primary purpose, then packs endpoint, state rule, side effects, auth scoping, rate limit, and cost into a few dense lines. Every sentence adds operational value 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?

For a single-parameter mutation with no output schema, the description covers the essential operational context: purpose, preconditions, side effects, auth, rate limiting, and cost. It does not describe response bodies or non-429 error cases, but those are less critical for selecting and invoking this 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 documents promise_id with a description covering the same 'Undo a kept|broken close — restore open' semantics, so schema coverage is 100%. The description adds no new parameter meaning beyond the schema, which matches the baseline of 3.

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

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

The description states a specific action ('Undo a kept/broken close — restore an open promise') on a specific resource, and makes the inverse relationship to pbx_promises_close immediately clear. It also includes the exact endpoint and the transition condition, leaving no ambiguity about what the tool does.

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

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

It explicitly states the precondition 'Only kept|broken → open', which tells an agent when the operation is valid. It implies when to use it (reverse a mis-click after a close) without naming pbx_promises_close as an alternative, but the usage context is clear enough.

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

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

With no annotations, the description carries the full burden and does well: it discloses rate limiting (≤30/hour/key → 429), tenant scoping (no cross-tenant), that raw media stays client-side, that audit records are durable, and that it is a managed pointer only, not a legal deletion SLA. Missing only the response shape, which is minor for a mutation.

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 dense first line is front-loaded and information-rich, but the description then repeats itself substantially in the second block (E.3 section restates KVKK-first redaction, tenant scope, durable audit, and the non-SLA caveat already given). This redundancy costs it, though the total length remains manageable.

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 six-parameter mutation tool with no annotations and no output schema, the description covers the critical behavioral facts an agent needs: scope, side effects, rate limit, audit, and limitations. The only gap is explicit response/return guidance and a named alternative, both minor here.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters (mode, phone, target_id, target_type, who, reason). The description adds context on mode values and lookup-by-target_id-or-phone, but nothing beyond what the schema provides. Baseline 3 is correct.

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 (redact/forget) and resource (derived index documents by id or phone), plus the KVKK compliance framing. It is distinct from siblings like pbx_persons_get or pbx_index_partial, though it doesn't name a sibling directly. The purpose is clear enough without opening the 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 when to use it (KVKK-first forget, managed SaaS) and mentions a companion list endpoint (GET /v1/pbx/redact/audit, sibling pbx_redact_audit), but gives no explicit when-not-to-use or prerequisite conditions. Usage is inferable but not spelled out.

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

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

With no annotations, the description carries the full burden and does real work: it discloses tenant scoping, that the audit is durable, and the critical caveat that only the derived index is cleared while raw media is not deleted by Temsor. Permissions and rate/retention limits are not covered.

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 scope statement and the index/media caveat are front-loaded and valuable, but trailing fragments like 'Number→flow managed SaaS; own PBX optional. No DID sales.' are cryptic, only loosely relevant to an audit listing, and dilute the core message.

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-style audit tool with no output schema, the description supplies origin (E.3), scope, returned dimensions, and deletion caveats. Return field detail is shallow, 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 description coverage is 100% and the single limit parameter is fully documented including its default, so the schema does the work; the description only echoes 'limit=20' in the URL example. Baseline 3 for high-coverage schemas.

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

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

States a specific verb and resource ('List recent KVKK forget actions') plus the returned fields (who/what/when + tenant scope), which clearly distinguishes it from the sibling pbx_redact that performs the redaction.

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?

Ties itself to the durable audit trail produced by POST /v1/pbx/redact (E.3) and warns 'not a legal deletion SLA', giving clear context for when the tool applies, though it names no explicit alternatives or prerequisites.

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

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

With no annotations provided, the description carries the full behavioral burden, and it delivers: API key shown once and hashed at rest, a rate limit with the exact 429 consequence, idle pricing, the x-temsor-pbx-key scoping mechanism, and the idle speech-recognition limitation. This goes well beyond a simple 'register' claim.

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

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

The text is short and front-loaded, but it repeats itself: 'API key shown once; stored hashed at rest' appears in both the first sentence and the second paragraph. Some extra behavior like 'No speech recognition while idle' is relevant, yet the duplication makes the description slightly less efficient than it could be.

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

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

For an 8-parameter registration tool with no annotations and no output schema, the description covers the essential behavioral context: return value, security handling, rate limit, cost, and API-key usage. Minor gaps remain, such as the exact response format and any prerequisites, but an agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, so the structured parameters already fully document fields like name, email, pbx_id, and webhook settings. The description does not add parameter-specific guidance, but it doesn't need to because the baseline 3 applies when the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource: 'Register a pilot PBX', immediately identifying the action and target. It also states the key result (returns pbx_id + API key) and clarifies this is a control-plane operation, distinguishing it from the many other pbx_* siblings, none of which are a registration tool.

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 clear context: rate limit of ≤5/hour/IP with 429, idle cost of $0, and a note that speech recognition is unavailable while idle. It doesn't explicitly name alternatives or when-not conditions, but the tool name and purpose make it obvious this is the registration entry point, so no exclusion is needed.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses important traits: it is a 'Demo index' (limited data), 'Idle $0' (cost-free), and 'No live PSTN' (no live telephony access). It also states the output shape ('call-graph path + transfer edges'). However, it does not cover potential limitations like pagination, auth requirements, or data freshness beyond 'demo'.

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 contains redundancy: 'Idle $0' appears twice. The structure jumps from purpose to analogy to filters to returns without a clear hierarchy. The informal phrasing ('voice-Google for call-ops') adds flavor but not clarity. While not overly verbose, the repetition and lack of front-loading of essential constraints hurt conciseness.

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

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

With no output schema, the description does explain the return type ('call-graph path + transfer edges'), which is essential. It also notes the demo nature and non-live status. However, it does not mention result limits, pagination, or how filters combine. Given the complexity of a full-text search over promises and facts, more details about expected output structure or result size would improve completeness.

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 57%, leaving ext, status, and competitor without descriptions. The description lists these as filters but adds no meaning beyond the names. It does add a clarifying note for stuck_after ('transfer/handoff hop'), which is useful. For a moderate coverage level, the description partially compensates but does not fully explain the undocumented parameters.

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

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

The description clearly states the core action: 'Agent archive search over call promises and facts' – a specific verb (search) over a defined resource (archive of promises and facts). It adds an analogy ('voice-Google for call-ops') and a negative ('not a receptionist bot') that convey intended usage. It does not explicitly differentiate from sibling tools like pbx_calls or pbx_facts, but the 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 description lists filters and states the return type ('call-graph path + transfer edges for orchestration'), implying it is for agent-side orchestration. However, it never explicitly says when to use this tool versus the many pbx_* siblings (e.g., pbx_calls, pbx_facts_get). No alternatives or exclusion criteria are mentioned, so guidance is implied at best.

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

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

With no annotations, the description carries the behavioral disclosure burden. It adds useful context: scoping via x-temsor-pbx-key, derived indexing, idle $0, and 'own PBX/Asterisk stays on customer.' However, it never explicitly states whether the operation is read-only, what the response looks like, or any error/rate-limit behavior, leaving gaps for an agent.

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, but it is telegraphic and repeats 'Idle $0' twice. Phrases like 'Advanced: own PBX/Asterisk stays on customer' are cryptic and not fully explained, so not every sentence earns a clear 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 0-parameter status endpoint, the description gives a reasonable overview: endpoint, scoping, counts, and idle cost. But there is no output schema, and the description does not clarify the response shape, possible error conditions, or the meaning of the 'Advanced' line, leaving an agent with incomplete expectations.

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 are zero parameters, so the baseline is 4. The schema already documents 'No input — scoped by x-temsor-pbx-key when set,' and the description repeats and reinforces that. No parameter-level meaning is needed beyond what exists.

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 this is a control-plane status endpoint ('GET /v1/pbx/status') and specifies its content: promise/orchestra/search counts and idle $0. It also explicitly says 'No DID sales,' which narrows scope. However, it does not directly distinguish this from sibling status-type tools like pbx_whisper_status, so it stops short of full differentiation.

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 intended usage is implied: check PBX control-plane status, counts, and idle cost. The 'No DID sales' statement provides a negative scope hint, and the x-temsor-pbx-key scoping note gives a prerequisite. But there is no explicit guidance about when to prefer this tool over sibling PBX tools or when not to use it.

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

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

With no annotations provided, the description carries the full burden – and it excels. It discloses the rate limit (≤30/hour/key → 429), HMAC signing via x-temsor-signature, the idle $0 cost, the 'No DID sales' restriction, KVKK compliance, and the advanced PBX/Asterisk customization. This is exemplary transparency about side effects, authentication, pricing, and legal constraints.

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 but every sentence carries operational value: rate limits, methods, events, signing, pricing, legal, and advanced options. It front-loads the core purpose and HTTP verbs before auxiliary details. Slightly long, but no filler; each 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 tool with 6 parameters, 0 required, and no output schema, the description covers the essential call patterns, event list, signing, and rate limiting. It omits explicit response format details (e.g., what GET returns) and doesn't describe the 'webhook_id' parameter beyond schema, but the usage modes are sufficiently clear for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the conditional semantics of 'url' (present → register, omit → list) and the ping behavior (with/without url). It also expands the events list and clarifies the HMAC signature mechanism, adding interpretive value that the bare parameter descriptions lack.

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 'Register or list outbound webhooks' – a specific verb+resource pair that tells the agent exactly what the tool does. It enumerates the event types (promise/fact/orchestra/redact) and clearly separates from siblings like pbx_webhooks_deliveries by focusing on registration/listing rather than delivery inspection.

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 clearly explains when to use POST vs GET and the ping option for test deliveries, effectively covering the main usage modes. It does not explicitly name alternatives like pbx_webhooks_deliveries, but the modes are so well defined that an agent can infer when this tool is appropriate. A slight bump would require an explicit 'use X instead for Y' note.

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

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

No annotations exist, so the description carries the full burden. It does disclose genuinely useful behavior: the 'stub or live' distinction and the 'HMAC when secret set' security detail, plus read-only nature implied by 'List'. However, phrases like 'No DID sales', 'KVKK', and 'Advanced: own PBX/Asterisk stays on customer' are marketing/legal noise that do not describe tool 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?

The core sentence is front-loaded and tight. But the trailing run of terse phrases — 'Idle $0. No DID sales. KVKK. Advanced: own PBX/Asterisk stays on customer.' — does not earn its place for an agent deciding whether to call the tool, diluting an otherwise compact definition.

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 low-complexity list tool with two optional parameters, the description covers purpose, endpoint, and security (HMAC). Yet with no output schema present, the return format/pagination of the delivery log is never described, and the noise phrases crowd out actionable context, leaving it adequate but with clear 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 100%, so the schema already documents limit and webhook_id. The description's endpoint example '?limit=20&webhook_id=' merely echoes the schema defaults rather than adding new meaning, so it stays at the baseline 3 with no added parameter insight.

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: 'List last N outbound webhook deliveries'. The scope is sharpened with '(stub or live)' and the delivery categories 'promise/fact/orchestra/redact/ping'. Purpose is clear and the name (deliveries vs the sibling pbx_webhooks) implies a log-of-deliveries distinction, though it never explicitly contrasts with pbx_webhooks.

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 — an agent can infer 'use this when you want to inspect the outbound delivery log' from the verb and the 'Durable log of Temsor→customer POSTs' line. However, it never names an alternative (e.g. pbx_webhooks for configuration) nor states any when-not-to-use condition, so routing decisions are left to inference.

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

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

Despite having no annotations, the description provides significant behavioral disclosure: it explains that mode=ready only indicates the env var is set, that live RTP is always false on forge, and that there is no production claim for ≤400ms latency. This is beyond what structured data would provide and gives honest expectations to the agent.

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 quite long and includes many caveats (e.g., 'No ≤400ms production claim', 'No DID sales') that may be tangential to the tool's core function. It is not front-loaded with a clear summary; the first line mentions capability and mode, but the rest is a list of clarifications. Some sentences could be trimmed without losing value.

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

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

The description covers key aspects: endpoint, meaning of mode, and lab mode. However, it lacks detail on the response structure (e.g., fields like live_rtp, listening) and does not explain what the agent should do with the status or how to interpret different values beyond mode. Given zero parameters and no output schema, more context on the returned data would be helpful.

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 description says 'No input — TEMSOR_RTP_* from process env.' The description does not need to add parameter semantics since there are none. The baseline for zero parameters is 4, which is appropriate here because the description correctly notes that inputs come from environment variables, not schema parameters.

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

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

The description states the tool's purpose: to report PBX whisper RTP status via GET /v1/pbx/whisper/status, and clarifies what 'mode=ready' means. However, it is not immediately clear to an agent that this is a read-only status check; the description is dense and includes many caveats that may confuse rather than clarify. It does distinguish itself from siblings by focusing on RTP status, but it does not explicitly say 'use this to check...'.

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: it is for checking the status of RTP via the endpoint, and it mentions a lab mode (TEMSOR_RTP_LAB=1) that adds lab_latency_ms. However, it does not explicitly state when to use this tool versus alternatives like pbx_status or pbx_whisper_suggest, nor does it provide any exclusions or conditions for when not to use it.

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

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

With no annotations, the description carries the transparency burden and does well: it discloses the ≤3 card limit, mock latency under 400ms, compat-stub behavior, idle cost, no-live-PSTN constraint, and lab-only TEMSOR_RTP_LAB behavior. It loses a point because terms like 'whisper cards' and 'in-call index' are not explained, and the lab_latency_ms field's role remains ambiguous.

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 and front-loads the core purpose, but it repeats 'Idle $0' and mentions lab_latency_ms twice. The first line mixes shorthand fragments without a clear logical order, making the text feel denser than necessary.

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 absence of an output schema, the description provides a reasonable high-level return contract (open promises/facts, max 3 whisper cards) plus important environment and latency constraints. It does not define exact card fields, auth, or error behavior, but it covers far more than the minimum for a two-parameter 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 100%, so the schema already documents call_id and partial_text; the description adds useful nuance about preferring the in-call partial index. However, the mention of 'optional lab_latency_ms when TEMSOR_RTP_LAB=1' is ambiguous because that field is not present in the input 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 that the tool 'Returns open promises and facts as whisper cards for agent handoff' and gives the concrete endpoint and payload shape. It is specific and useful, but it does not explicitly differentiate itself from related PBX siblings such as pbx_whisper_status or pbx_promises, so it falls short of a 5.

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

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

Usage context is implied: it is for live-agent handoff, prefers an in-call partial index, and the 'No Telnyx/DID/live PSTN' caveat signals it is not for live telephony. However, there is no explicit 'use this instead of X when...' guidance, so the agent must infer when this tool should be selected over its 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?

With no annotations, the description fully discloses behavioral traits: normalizes to E.164, classifies line types (including special ranges), resolves province for Turkish landlines, and returns both E.164 and national notation. Also honestly states the limitation on operator detection with portability caveat.

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?

Well-structured: opening summary, usage context, detailed behavior, and honest limitation. Each paragraph is purposeful, though the last paragraph could be slightly tighter without losing clarity.

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 no output schema, the description covers key aspects: input format, two output notations, line type classification, province resolution, and operator caveat. It is fairly complete for a complex validation tool, though explicit output structure details would enhance completeness.

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% (both parameters described), so baseline 3. The description adds significant semantic value by explaining that defaultCountry defaults to TR, and how Turkish numbers are handled in depth (area codes, special ranges). This goes beyond the schema's minimal descriptions.

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 validates and normalizes phone numbers to E.164, classifies line type, and resolves province for Turkish landlines. It distinguishes from sibling tools by focusing on phone validation with Turkish specifics.

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 recommends use in signup and checkout flows for canonical storage and early error rejection. Also clarifies what the tool does not do (report current mobile operator) and provides caveats about number portability, helping the agent avoid misuse.

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

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

No annotations are provided, so the description carries the transparency burden. It discloses normalization of abbreviations, province/postcode cross-checking, misspelling repair, confidence scoring, and an `unparsed` list so nothing is silently dropped. It lacks explicit error-handling details, but is otherwise transparent for a parser tool.

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

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

The description is compact and front-loaded: the first sentence states the core function, the second adds behavioral guarantees, and the third provides usage context. Every sentence contributes value without unnecessary padding.

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 parsing tool with no output schema and no annotations, the description covers the input nature, output components, normalization behavior, confidence score, unparsed fallback, and target use cases. This gives an agent enough context 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?

Schema description coverage is 100%, so a baseline of 3 applies. The description adds useful context about free-form Turkish addresses and cross-checking the province against the postcode, but it does not materially elaborate on the `defaultProvince` parameter beyond what the schema already states.

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

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

The description states a specific verb and resource: 'Splits a free-form Turkish address into neighbourhood, street, building, floor, flat, district, province and postcode.' This clearly distinguishes it from sibling validation and invoice tools in the Turkish toolset.

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 context for when to use the tool: 'Built for shipping, checkout and CRM systems that receive Turkish addresses typed by humans.' It does not explicitly name alternative tools or state when not to use it, but the use-case framing is 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?

With no annotations provided, the description carries the full transparency burden. It discloses important behavior: Hijri-calendar feasts are read from an announced table, and years without official announcements return `confirmed:false` rather than guessed values. It does not describe the full return shape or behavior when both `addDays` and `end` are supplied, but the core behavioral caveat is well covered.

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 three short sentences, front-loaded with the core purpose and followed by a necessary caveat and use-case list. Every sentence earns its place; the final fragment is slightly informal but not wasteful.

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 explain return values more fully; it only mentions `confirmed:false` without describing the overall response structure. It also does not address edge cases like supplying both `addDays` and `end`, or whether start/end dates are inclusive. For a 4-parameter tool with no annotations and no output schema, this leaves some important 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 100%, so the baseline is 3, but the description adds meaning by defining business days in the context of Turkish holidays and half-day eves, which directly clarifies how `addDays` and `countHalfDaysAsWork` should be interpreted. It does not clarify the relationship/conflict between `addDays` and `end`, but the schema already documents each parameter individually.

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-resource pair: 'Adds business days or counts them between two dates' and clearly scopes it to Turkish public and religious holidays. This distinguishes it from the sibling validation and lookup tools, which serve entirely different purposes.

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 names target use cases: 'delivery promises, SLA clocks, payment terms and shipping estimates.' It does not mention when not to use the tool or name alternatives, but the context is clear enough for an agent to select it appropriately.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It explains the ISO 7064 check-digit computation, left-padding of the account, defaulting of the reserved digit, and the important edge case that unknown bank codes still produce a structurally valid IBAN with bankName null.

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 concise sentences with no filler: the first states the core action, the second defines the output format and construction rules, and the third covers edge-case behavior. Information is front-loaded and every sentence earns its place.

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

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

The description covers format, algorithm, parameter behavior, and edge cases, which is strong for a tool with no output schema. It never explicitly states the full return shape beyond mentioning bankName, but the IBAN format is fully specified and the key behavioral caveats 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 the baseline is 3. The description adds meaningful context beyond the schema by explaining how the reserved digit defaults to 0, how account numbers are padded, and how the bank name resolution behaves for unknown codes.

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 resource: 'Builds a Turkish IBAN from a 5-digit bank code and account number.' It clearly distinguishes the generation/construction action from sibling validation tools like iban_validate, so an agent can tell what the tool does at a glance.

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 intended use is implied strongly by the verb 'Builds' and the output-oriented details, but the description never explicitly tells the agent when to prefer this tool over sibling tools such as iban_validate or bic_validate. There is no direct when-to-use or when-not-to-use guidance, so the agent must infer the boundary.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that totals are recomputed and sent totals ignored, VKN/TCKN checksums are verified, the amount is written in Turkish words, and the document is neither signed nor transmitted. These are meaningful behavioral traits beyond a generic 'builds an invoice' statement and set clear expectations for side effects.

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

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

The description is front-loaded with a one-sentence summary followed by a focused paragraph of necessary context. Every sentence adds relevant information about validation, rounding constraints, non-goals, or next steps, with no wasted words.

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 high complexity—17 parameters, nested objects, no output schema—the description covers input format, processing behavior, validation, limitations, and the nature of the returned artifact. It tells the agent enough to know when and how to invoke the tool and what to expect back without requiring an output schema.

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

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

Schema coverage is 53%, so the description adds value by explaining how parameters affect output: line amounts/VAT subtotals/payable amount are recomputed, checksums on tax numbers are verified, and the amount is written in words. This goes beyond the schema's structural descriptions. It does not systematically explain every parameter, but the schema already covers many details and the description adds the most consequential behavioral semantics.

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

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

The description opens with a specific verb and resource: 'Builds a UBL-TR e-Invoice or e-Archive XML document from plain JSON.' It clearly states the tool's transformation (JSON to XML), its domain (Turkish e-Invoice/e-Archive), and implicitly distinguishes it from siblings like tr_invoice_parse by focusing on construction rather than parsing.

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 clear context: use this when selling into Türkiye and needing a UBL-TR document before the integrator step. It also communicates non-goals explicitly ('It does not sign the document and does not transmit it'), which helps the agent understand where this tool fits in a workflow. It does not explicitly name alternative tools or exclusion conditions, so it stops short of a 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?

No annotations are provided, so the description must cover behavioral traits. It does disclose key behaviors: namespace-agnostic parsing, normalizing single-line documents to arrays, and reporting amount mismatches via warnings instead of returning wrong totals. However, it does not mention error handling, rate limits, or other operational specifics, which is acceptable given no annotations but still some gaps exist.

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

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

The description is a few functional sentences, front-loaded with the core purpose and behavior. The third sentence about 'engineering time' is a few rhetorical flourish that does not add operational value, making it slightly less crisp but still efficiently structured.

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 a single parameter, no annotations, and no output schema, the description covers essential what the tool does and critical anticipations: defines the output categories, explains normalization policy, and warns about amount mismatch. It lacks a sample output format and error handling notes, but for the complexity level, it is reasonably 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 only parameter 'xml' is fully described in the schema with 100% coverage. The description adds behavioral context about processing the input (namespace handling, normalization) that goes beyond the schema description, providing some added meaning about how the input is interpreted.

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 explicitly states the tool parses UBL-TR e-Invoice or e-Archive XML into clean JSON and specifies the output includes parties, line items, taxes, and totals. This clearly distinguishes it from sibling tools like tr_invoice_build (building invoices) and other validation tools.

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

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

The description implies the tool is for parsing e-Invoice XML but does not explicitly state when to use it vs. alternatives. It does not mention counterpart tools like tr_invoice_build or what should be used for building invoices, leaving usage context 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?

With no annotations to carry the burden, the description provides deep behavioral context: statutory references, ceiling application semantics, which taxes apply or don't, and the tool's limits. Goes well beyond a basic description of what the tool calculates.

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-dense with no wasted sentences; even the legal citations and tariff context serve as behavioral cues for the agent. The prose is slightly ornate in the middle section but remains functionally relevant to understanding the tool's behavior.

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 computing three legal entitlements with tax nuances, the description covers input semantics and the legal limitations thoroughly. Missing a description of the return-value shape, which would help agents chain this with downstream logic.

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 has 100% coverage with rich parameter descriptions, so the baseline is raised. The description adds value by explaining how parameters interact ('the ceiling is applied to the monthly wage, not the total') and the tax implications of the salary inputs. This enriches the agent's understanding of what changing the parameters actually computes.

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?

Uses specific verb 'Computes' with clearly enumerated resources (severance, notice, annual-leave) and inputs. Distinguishes itself from sibling validator/parser tools by describing computation logic and legal basis. The description reads as a domain-specific calculation tool rather than a generic validation function.

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 lists boundary conditions with the 'What this will not tell you' section, warning about entitlement determination and legal consequences. Clearly states tax treatment (stamp tax, income tax exemption). Lacks explicit naming of alternative/sibling tools for when this endpoint is inappropriate, preventing a 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?

No annotations are present, so the description carries the full burden. It discloses non-obvious behaviors: 'bin' never 'bir bin', the kuruş part is read separately, and both decimal formats are accepted and disambiguated automatically. It does not describe return shape or error handling, but it adds meaningful behavioral detail beyond the schema.

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 paragraphs, front-loaded with the core action and followed by useful Turkish-language rules. The final sentence is slightly promotional ('no off-the-shelf API until now') but still reinforces the use case, so there is minimal waste.

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

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

For a tool with no output schema and no annotations, the description should clarify return value and edge-case behavior; it does not. It covers purpose, use cases, and key formatting rules well, but wrapHash behavior and the exact output format remain 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 description coverage is only 50%, and the description adds valuable amount-format semantics ('1.234,56' and '1,234.56' accepted) beyond the schema. However, currency is only self-evident from its enum values and wrapHash is left completely unexplained, so the description 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?

The description opens with a specific verb and resource: 'Writes a monetary amount out in Turkish words'. It also differentiates the tool from generic libraries by calling out Turkish-specific rules and the invoice/cheque/promissory-note context, 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 explicitly frames the tool for invoices, cheques, and promissory notes, and notes it is a mandatory Turkish e-invoice field, giving clear when-to-use context. It does not name alternatives or state when not to use it, but the context is strong enough for selection.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It reveals key edge-case behavior: returns null with confidence none for out-of-range prefixes, and explicitly says it does not invent a district. It could go further by describing the success response shape or behavior for malformed lengths, but the most consequential behaviors are covered.

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 purpose is front-loaded in the first sentence, and the rest of the description earns its place by explaining validation mechanics, failure behavior, and scope limitations. It is slightly repetitive about the five-digit/plate-map rule, but overall it is tight and free of 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 single-parameter tool with no output schema and no annotations, the description covers the main success behavior (province resolution), the main failure mode (null with confidence none), and the scope limitation (no district). It leaves minor ambiguity about malformed input handling and exact return fields, but the overall picture is largely 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 input schema has 100% description coverage for the single parameter, so the schema already explains postalCode as a Turkish 5-digit code with optional spaces. The description adds useful domain context about the plate-map, but it does not add new parameter syntax or formatting details beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Validates a 5-digit Turkish postal code and resolves the province from the first two digits (plate map).' It clearly distinguishes the tool's scope by stating it does not resolve districts, which separates it from broader address/validation siblings.

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

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

The description explains when to use it: for shape validation and province-level resolution. It explicitly excludes district-level resolution and notes that the full PTT directory is needed for that, giving the agent a clear boundary. It does not name a sibling tool, but the scope guidance is strong enough to route the agent 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does this thoroughly: it states that the tool only builds text, not a QR image; that it normalizes and validates the Turkish IBAN using ISO 7064 mod-97; that non-TR IBANs and non-TRY currencies are rejected; and that it does not send money. This gives an agent a clear and accurate model of the tool's side effects and constraints.

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 front-loaded with a clear one-sentence summary and then provides necessary technical detail. There is minor redundancy between 'Text only — no PNG' and 'does not render a QR image,' but the extra context about EMV-style TLV, CRC-16/CCITT-FALSE, and validation rules is purposeful and 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 tool with six parameters, no annotations, and no output schema, the description is substantially complete: it covers input requirements, validation behavior, optional fields, technical format, and exclusions. The only notable gap is that it never explicitly states the return type or structure, though 'payload' and 'Text only' strongly imply a string result.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining that the amount becomes a 12-digit kuruş value, that omitting it produces a static QR where the payer enters the amount, and that explanation maps to application free field 10. This enriches the parameter meanings rather than merely repeating property descriptions.

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 and resource: 'Builds a person-to-person TR Karekod (FAST) payment payload from IBAN, name and optional TRY amount.' It also explicitly differentiates itself from rendering or money movement with 'Text only — no PNG' and 'This does not send money and does not render a QR image,' which distinguishes it from siblings like pay_epc_qr without ambiguity.

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 clearly: it is for Turkish FAST person-to-person QR payloads. However, the description does not explicitly say when to prefer this tool over alternatives such as pay_epc_qr, nor does it state when not to use it. The reader infers the scope from 'Turkish' and 'FAST' but receives no explicit 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?

With no annotations provided, the description carries the full burden, and it delivers thoroughly. It explains the legal rules under Turkish notification law (7201) and HMK, including the deemed-received calculation, holiday shifting, and arife exceptions. It also discloses constraints (only 'hmk' supported, no guessing of period days) and the meaning of basisDate for electronic notifications. This goes well beyond what a schema could 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?

Although lengthy, every sentence contributes substantive legal or usage information. The purpose is front-loaded, followed by relevant legal background, then explicit limitations. There is no fluff or redundancy; the density is justified by the tool's complexity.

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 complex legal-computation tool with 8 parameters and no output schema, the description is remarkably complete. It explains the underlying law, the computation logic, edge cases (arife, judicial recess), and what it does not do. An agent has all necessary context to decide whether and how to call the tool, and to interpret its result.

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 each parameter already has a descriptive definition (e.g., 'type' explains the meaning of basisDate). The description adds valuable legal context—such as why basisDate for electronic is the reached date, and the significance of hasAttorney—which enriches understating beyond the schema. This is more than the baseline 3, but the schema already does a lot of work.

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

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

The description opens with a precise, verb-led statement: 'Computes the deemed-received date and the HMK deadline (with holiday shifting) for a Turkish notification, from the date the underlying event actually happened.' This clearly identifies the resource (Turkish notification deadlines) and the exact computation performed, distinguishing it from all sibling validation/lookup tools.

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

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

The description explicitly states what it does NOT cover: 'What this will not tell you: whether the notification was itself valid, or what a specific periodType... is in days for your case' and advises the caller to supply periodDays themselves. It also notes the limitation to the 'hmk' law family. However, it does not explicitly compare against alternative tools since none of the siblings are similar, so it falls just short of a 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?

With no annotations provided, the description carries the full burden and excels by explicitly stating pure local computation, no upstream calls, microsecond latency, and deterministic output. It also mentions that it resolves richer info beyond a simple boolean, setting clear behavioral expectations.

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 tight and well-structured: the first paragraph explains what the tool validates, and the second adds value-added resolution and performance characteristics. No redundant or irrelevant 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 a simple input schema and no output schema, the description covers the tool's scope, the extra resolution it performs, and its non-network, deterministic behavior. It provides sufficient context for an agent to know what to expect from calling it.

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

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

Schema coverage is 100%, so baseline is 3. The type parameter description ('Omitted → inferred from the format') and the tool's list of supported formats add meaningful context about how the value is interpreted. The value description is minimal but the overall purpose makes it clear enough.

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 validates a specific list of Turkish identifiers and numbers, with type auto-detection, from a single endpoint. The title reinforces the purpose, and the enumeration of supported types distinguishes it from more specific sibling validators.

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 the type is unknown or multiple types are involved, but it does not explicitly compare with dedicated validators like iban_validate or isbn_validate. There is no direct 'when not to use' guidance, leaving the decision to inference.

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

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

With no annotations provided, the description carries the full disclosure burden and does so thoroughly. It explains the supported rates, that withholding is a fraction of VAT or a GİB code, that the 2026 threshold is reported but `applies` is always null, and that the result is not a legal opinion. This goes well beyond a typical tool description.

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, front-loaded with the main purpose, and every sentence supplies useful information. It packs domain context, parameter behavior, threshold caveat, and a legal disclaimer into three sentences without fluff or repetition.

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 partially explain return behavior, and it does: it mentions net/VAT/withholding splits, the threshold comparison, and the always-null `applies` field. However, it does not fully enumerate the output structure or handling of invalid inputs, which would have made 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema. It clarifies that withholding is a fraction of the VAT itself, narrows the fraction range to '2/10 through 10/10', and explains the named-code option from the GİB partial-withholding list, which enriches the parameter understanding.

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 resource: 'Splits a Turkish amount into net, VAT and (optionally) withholding.' It further distinguishes this calculator from sibling invoice/validation tools by naming the exact Turkish VAT domain concepts (KDV dahil/hariç, tevkifat) and the split responsibility between seller and buyer.

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 clearly states when this tool should be used: 'For invoice lines and checkout totals that have to show KDV dahil / hariç' and for withholding (tevkifat) situations. It gives strong context and domain applicability, though it does not explicitly name alternatives or state when not to use it.

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