kadro-mcp-server

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

With no annotations provided, the description carries the full burden. It discloses key behaviors: only a 15-minute hold, no charge, no payment information accepted, and idempotency for retries. It does not mention return format or error handling, but the disclosed behaviors are important and well-stated.

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, well-structured paragraph that front-loads the purpose and key constraints. Each sentence adds value; there is no fluff. It could be slightly more compact, but it is efficient and readable.

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 11-parameter tool with no output schema, the description covers the main behavioral aspects but omits what the response contains (e.g., reservation ID) and error conditions. It also does not describe the other required parameters. It is adequate for a basic call but not 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 only 45%, so the description must compensate. It adds meaning to start_time (ISO 8601, at least 6 hours in future) and idempotency_key (stable for retries). However, it does not explain the other required parameters like shoot_type_id, package_id, city_id, or address coordinates, which remain underspecified.

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 verb 'Book' and the resource: a specific photographer, package, date/time, and address on the user's behalf. It also distinguishes itself from siblings by explicitly mentioning the follow-up get_payment_link, which is a different operation. 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?

It gives explicit usage guidance: 'Immediately follow this with get_payment_link' and instructs the agent to give that URL to the human. It also specifies when to use idempotency_key for retries and states that no login is required. This is strong, actionable 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, the description carries the burden, and it discloses key behavioral constraints: this is a URL for the human user, the server takes no further action, and the agent must not complete the flow. It could add details about return format or failure modes, but the security-relevant behavior is clearly 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 front-loaded with the core purpose and then provides essential operational warnings. Every sentence adds value; no filler or redundant information.

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

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

For a single-parameter tool with no output schema, the description is nearly complete: it explains the output (a URL), the intended recipient, and critical don'ts. A minor omission is the exact response format, but the operational guidance is sufficient 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?

The schema already describes the only parameter, slug, as the value from create_reservation, so the description adds little beyond that. Baseline 3 applies because schema coverage is 100%.

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: obtain a URL for a reservation's payment step. It also clearly distinguishes this from sibling tools like get_reservation_status or create_reservation by framing it as the final purchasing step.

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 instructs when to use it (final step to complete a reservation) and when not to perform additional actions (never ask for card/OTP/password, never open or submit the URL). This gives an agent concrete guardrails.

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 that the tool rejects shoot_type_id if the photographer doesn't offer it, and emphasizes 'real, currently bookable' packages, indicating filtering of invalid/expired options. However, it omits details like error responses, return format, pagination, or authentication requirements, which are important for a tool with no output schema and no 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 two sentences, front-loaded with the primary action, and includes a practical cross-tool reference. It is efficient with no redundant information, making it easy to parse quickly.

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 two-parameter list tool with no output schema, the description is reasonably complete. It specifies the return includes prices and package ids (implied by 'Use the returned package id'), and clarifies validation behavior. However, it does not describe the exact output structure (e.g., array of objects) or potential error conditions, which could leave an agent uncertain about parsing the response.

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% (only photographer_uid has a description). The description adds meaning for shoot_type_id by stating it rejects invalid values, and clarifies the unit (Toman) and purpose of the parameters. Yet it does not fully compensate for the missing shoot_type_id description, nor does it explain the expected format of the uid 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 clearly states the action: listing packages, with specific scope (photographer and shoot type), and clarifies it returns real, currently bookable packages with prices in Toman. It also differentiates itself from siblings by mentioning the returned package id is used with create_reservation, which helps an agent understand the tool's role in the workflow.

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 cross-tool hint ('Use the returned package id with create_reservation') and implies the tool is for obtaining package prices, but it does not explicitly state when to use this tool versus alternatives like search_photographers or search_shoot_types. It lacks explicit exclusion or alternative routing, though the parameter description for photographer_uid points to search_photographers, providing indirect 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 behavioral burden. It does well by explaining the meaning of 'paid_awaiting_photographer_confirmation' and warning against treating that status as final. This is valuable non-obvious behavior beyond the bare tool 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 is compact and efficient: one clear opening sentence followed by an essential status-value guide with an important caveat. Every sentence contributes directly to correct tool usage.

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 lookup tool with no output schema, the description provides the critical domain knowledge: the status values and the meaning of the ambiguous one. It does not detail error behavior or response shape, but the low complexity makes that gap minor.

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 only parameter, slug, and its origin from create_reservation. The description adds no parameter-specific detail, which is acceptable because schema coverage is 100%.

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 specific operation—checking whether a reservation has been paid and confirmed—and supplements it with the exact status values, making the tool's function unambiguous. It is easily distinguished from siblings like create_reservation or get_payment_link.

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 indicates when the tool should be used: whenever an agent needs to determine a reservation's payment and confirmation state. It does not explicitly mention exclusions or alternative tools, but the sibling context makes the intended use 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?

No annotations are present, so the description carries the behavioral disclosure burden. It states the tool returns real, bookable photographers and lists the returned fields, but does not disclose pagination, sorting, error conditions, or authentication requirements. For a read-oriented search tool this is adequate but not deeply 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?

Two sentences with no filler. The core action is first, the prerequisite is embedded, and the return fields are listed compactly. 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?

For a two-parameter search tool with no output schema or annotations, the description covers the key context: input source, optional filter, output fields, and the importance of the returned uid. It does not specify the response envelope (e.g., array), pagination, or error behavior, so it stops 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 coverage is 100% – both parameters already have descriptions in the input schema. The description restates the source of shoot_type_id and the optional narrowing by city_id, but adds no new semantic detail such as value formats, range constraints, or dependencies 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 ('Find real, bookable photographers') with an explicit input (shoot_type_id, optionally city_id) and output fields. It references search_shoot_types as the source of the id, which distinguishes it from siblings like create_reservation and get_reservation_status, and clarifies it as a discovery step.

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 it after getting a shoot_type_id from search_shoot_types, and use the returned uid for every later call. It lacks explicit when-not-to-use instructions or named alternatives, but the workflow sequencing 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 behavioral burden. It discloses that the tool returns service types each with a numeric shoot_type_id, and 'List' implies a read-only operation. For a zero-parameter lookup, this is adequate behavioral disclosure.

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

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

Two sentences with no redundancy. The purpose is front-loaded, and the usage direction is delivered in a single imperative sentence. Every word 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 simple no-parameter list tool with no output schema, the description fully covers what the tool returns, how the output is structured, and when to call it. No essential information is missing.

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

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

The tool has 0 parameters, so the baseline is 4. The description adds no parameter semantics, but none are needed; the empty schema already fully covers this aspect.

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

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

The description names a specific verb ('List') plus a specific resource ('photography/videography service types Kadro offers') and clarifies the key output ('numeric shoot_type_id'). This clearly distinguishes it from sibling tools like search_photographers and get_photographer_packages, which operate on different entities.

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

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

The description gives an explicit trigger condition: 'Call this first if you don't already know the id for the kind of shoot the user wants.' It does not name explicit alternatives or when-not-to-use cases, but the usage context is clear and actionable.

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