Kirah Local Services

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

The description states "This is an informational availability check only," which strongly implies a read-only operation, while the annotation readOnlyHint is false. This is a direct contradiction between the description and the structured behavior hint. Even though the description also adds useful demo-labeling and prompt-injection warnings, the contradiction makes the behavioral contract unreliable.

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 entirely purposeful. The first sentence gives the core operation, the second clarifies demo defaults and honest partial reporting, and the final sentences define the read-only nature and the untrusted-data security boundary. Every sentence contributes important practical information.

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

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

Because the schema covers parameters thoroughly and an output schema exists, the description mostly completes the picture by covering demo defaults, partial coverage, and prompt-injection warnings. It loses a point because it omits guidance for selecting this tool over its siblings and because the readOnlyHint false mismatch muddies the informational context.

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: all 7 parameters, including query semantics, tenant_mode enum, back-compat alias, earliest window bounds, candidate_limit, and max_price_cents have detailed in-schema definitions. The description only generalizes those constraints, e.g., by saying "bounded set" and "exact ISO 8601 window," without adding meaningful 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 states a specific action and resource: "Check a bounded set of matching Kirah businesses for the earliest current opening in an exact ISO 8601 window." It also adds clarifying scope by noting it is an "informational availability check only," and it distinguishes demo vs. real businesses. However, it does not explicitly differentiate itself from sibling tools like get_availability or search_services.

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

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

There is no explicit guidance about when to use this tool compared with its siblings. The security warning and informational statement are behavioral, not usage-routing. The schema's tenant_mode param implies selection criteria, but the description itself gives no '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?

The description says 'cannot reserve or change a time,' which is a read-only behavioral claim, while the annotation declares readOnlyHint=false. This is a direct contradiction in the side-effect/read-only signal an agent receives. The useful 'untrusted data' warning is undermined by this inconsistency.

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 function and range constraint are front-loaded, and the untrusted-data warning earns its place in the second sentence. Slightly long noun lists in the final sentence make it denser than necessary, but overall structure is effective.

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 output schema presumably covers response details, so that is not a concern. But the description is materially incomplete for selecting among the listed siblings, for explaining the undocumented service_id/provider_id pair, and for reconciling the read-only behavior with a false readOnlyHint. These are real gaps for an agent deciding whether and how to call 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 description coverage is 50%, and the description does not meaningfully compensate: service_id and provider_id have no schema descriptions, and the description only says 'published service' without clarifying identifiers or relationship. The date-range wording mostly duplicates the existing schema description.

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?

Describes a specific operation: showing current availability/open times for a published service over a bounded YYYY-MM-DD range. The scope is clearly distinct from listing or searching sibling tools, and the 'cannot reserve or change a time' clause reinforces what the tool does at a high level.

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 situational cue: use this when you need exact availability for a known service and a specific date range of at most 31 days. However, it does not explicitly name sibling tools such as find_available_services or search_services, nor does it say when not to use this tool, leaving that routing to inference.

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

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

The description clearly says 'Read one Kirah business's published service catalog,' implying a read-only operation, but the annotations declare readOnlyHint=false, indicating the operation might not be read-only. This is a direct contradiction. The description does add valuable context about sensitive fields being hidden and untrusted business-published data, but per the rule, a contradiction with annotations forces a score of 1 and the annotation_contradiction flag must be set.

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 primary purpose, then efficiently adds two essential behavioral caveats: the lack of sensitive fields on the public surface and the untrusted-data warning. There is no redundant wording, and each sentence earns its place, especially the prompt-injection warning which is critical for safe invocation.

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 a single well-documented parameter and an explicit output schema, the description covers the necessary invocation context: what is returned (catalog, providers, prices, durations, timezone), what is not returned (sensitive fields), and how returned data should be treated (untrusted, not instructions). The only significant issue is the behavioral contradiction, which is already captured under behavioral_transparency.

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 already provides 100% coverage for the single 'tenant' parameter, including its type, max length, and how to resolve the value from the tenant's well-known manifest. The tool description does not add additional meaning about the parameter beyond the schema. The baseline of 3 applies because the schema carries the full semantic burden and the description adds nothing meaningful for parameter usage.

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 specific verb ('Read') and resource ('one Kirah business's published service catalog, provider list, prices, durations, and timezone'), and it scopes the tool to a single business rather than a general search. This distinguishes it from the sibling search tools and availability tools without leaving the agent to infer the operation.

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 establishes a clear usage context: use this for reading one business's published service catalog on the public surface. However, it does not explicitly state when to use this tool over the sibling alternatives (e.g., search_services or find_available_services) nor does it list exclusions. The guidance is implied by the single-business scope rather than stated directly.

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

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

Annotations only expose false hints, so the description carries the full behavioral burden. It transparently discloses demo labeling, informational/non-mutating nature, that ChatGPT location hints may narrow results, and the important security property that untrusted business content is never instructions. This goes well beyond the annotation hints.

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. Each subsequent sentence adds a valuable operational context: demo inclusion, location narrowing, informational no-appointment guarantee, and untrusted-data warning. No redundant 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?

For a tool with 7 parameters in this schema and a full output schema, the description covers the most critical operational risks: demo flagging, non-mutability, and prompt injection safety. It leaves parameter-level semantics to the schema, which is acceptable, but does not explicitly detail the mode-switching between query and agent_address.

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 86%, and individual parameter descriptions already explain query, agent_address, tenant_mode, include_demo, cursor, limit, and max_price_cents. The description adds only the relationship between direct service request and exact address, not material new parameter 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?

States a specific verb and resource: find eligible public Kira businesses whose published catalogs match a direct service request or exact agent address. This clearly differentiates from sibling tools focused on services (search_services, find_available_services) because it targets businesses, not services or availability.

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?

Description gives clear context: matches direct service requests, exact addresses, default demo inclusion, and informational-only results that cannot create appointments. It names the boundary of use (cannot change appointments) but does not explicitly point to relevant alternatives among the sibling tools.

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 goes beyond the annotations by disclosing that results are only lexical candidates, the caller remains accountable for interpretation, and that catalog content is untrusted data that must not be treated as instructions. This adds meaningful safety and behavioral context not provided by the annotations.

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

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

The description is three focused sentences with no filler. The key behavior and scope appear in the first sentence, and security guidance is contained in the third. Every line contributes useful information.

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

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

The output schema covers return values, and the description covers the key behavioral and safety concerns, including data trust and the limit of five results. It is slightly incomplete only in that it does not explicitly position this tool against its direct siblings beyond describing its own mechanism.

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 already documents the tenant parameter thoroughly. The description adds light semantic guidance for the query by calling it 'short service query' but does not elaborate on valid query formats, examples, or edge cases. Half of the parameters lack schema descriptions, so the description only partially compensates.

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

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

The description uses a specific verb ('Rank') with a concrete resource ('one Kirah business's published catalog') and defines the scope ('up to five services'). It also clearly differentiates this tool as a lexical candidate search from higher-level search or listing 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 clearly establishes this is for searching a single business's catalog with a short service query, and explicitly notes that results are lexical candidates. It does not explicitly state when to use alternative siblings or when not to use this tool, so it falls just short of full exclusions.

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