Jan Linketscher

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

Annotations already declare write, non-idempotent, open-world behavior; the description goes further by disclosing the elicitation handshake, the manual-confirmation fallback, and the downstream effect (Cal.com emails a confirmation with reschedule/cancel links to the attendee address). It does not cover failure modes such as a slot being taken between get_availability and booking, which is the one behavioral gap for a booking 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?

Front-loaded with the one-line purpose before procedural detail, and every sentence carries operative information (approval flow, required fields, downstream email). It is dense and the elicitation parenthetical is heavy, but the complexity of the two-mode flow justifies most of the length.

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 7 parameters, an output schema, and a multi-step conditional flow, the description supplies everything an agent needs: precondition (slot from get_availability), the two execution paths, and the required user-facing confirmation. Return values are covered by the output schema, so nothing material 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?

Schema coverage is high (86%), so the baseline is 3, but the description adds genuine meaning: 'start' is constrained to get_availability output, name/email must be the user's real values, and 'confirmed' is scoped to clients without elicitation. 'meeting_type' (the only enum) is still left unexplained, which holds it below a 5.

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?

Names the specific verb and resource ('Book a call with Jan Linketscher') and immediately establishes scope ('on behalf of your user'), which distinguishes it from the sibling read tools (get_availability, list_meeting_types). An agent knows exactly what this tool produces 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?

Explicitly requires that 'start' come from get_availability, names that sibling as the upstream step, and branches into two modes (elicitation form mode vs. manual approval with confirmed: true). It also gives an explicit prohibition ('never invent' name/email), leaving no ambiguity about when and how to call 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?

Annotations already declare readOnlyHint, destructiveHint=false and idempotentHint=false, so safety is covered; the description adds real behavioral context on top: the default lookahead window, the hard 90-day ceiling, and the timezone rendering (ISO 8601 with offset, text answer in Europe/Berlin). It stops short of describing pagination or what happens when a meeting type has no slots.

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 dense sentences with no filler, and the core resource statement is front-loaded. Slightly telegraphic in the middle (enum recap) but every sentence carries 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?

With an output schema present, return-value documentation is not required, and the description still covers the essentials (timezone of the rendered answer, date window defaults and limits, meeting types and durations). Only minor gaps remain, such as how slot lengths differ per meeting type or any auth requirement.

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 contributes beyond the schema by giving human-readable labels and durations for each enum value ('Kennenlernen, 30 min', 'Sparring, 60 min') and restating the date-range defaults and 90-day cap. These details are not present in the enum alone and materially affect slot interpretation.

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 first sentence names the concrete resource ('free time slots for a call with Jan Linketscher'), which is specific enough to separate it from siblings like book_meeting (which reserves a slot) and list_meeting_types (which returns types, not slots). An agent can identify intent 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?

Usage is only implied: the tool returns free slots, so an agent can infer it is the precursor to book_meeting. The description never states when to call it, when not to, or names the booking sibling as the follow-up action.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, covering the safety profile. The description adds the return format (Markdown with front matter), which annotations cannot express, but says nothing about missing-slug behavior or permissions.

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 short sentences, front-loaded with what the tool returns and followed by the input source. No redundant or filler content.

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

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

For a single-parameter read tool with an output schema and full annotation coverage, the description supplies purpose, format, and input provenance, which is nearly everything needed. Minor gap: no mention of failure behavior for an invalid slug.

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 the schema already explains that slug is the last part of /essays/<slug>. The description adds real value by naming the tools (list_essays, search) from which the slug should be sourced, going beyond the schema's static format hint.

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 ("Full text of one essay") plus the output format ("as Markdown (with front matter)"). It is clearly distinguishable from the sibling list_essays, which returns a list rather than a single document.

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?

"Use the slug from list_essays or search" gives concrete context for obtaining the required input and routes the agent back to the discovery tools. It does not state any when-not conditions or error handling, so it falls short of a full 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?

Annotations already declare readOnly, idempotent, non-open-world, and non-destructive, so safety is covered. The description adds one genuinely useful trait beyond that: content is in German. It says nothing about caching, freshness, or output size, so this is adequate rather than rich.

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?

One dense sentence that front-loads the subject's identity and enumerates the sections without filler. The trailing 'Content is in German' is short and load-bearing. Slightly list-heavy but 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?

With an output schema present, returns need not be explained, and annotations carry the safety profile. The description covers identity, scope, language, and section coverage, leaving only minor gaps such as how sections interact with structured output.

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 enum parameter is fully documented in the schema, including the default and the 'structured output is always complete' caveat. The description maps some enum values loosely (background, writing, contact) but adds no real 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?

States precisely whose profile this returns (Jan Linketscher), the resource type (profile sections: role, background, writing, contact), and the content language. This clearly separates it from siblings like get_essay, list_essays, and book_meeting, though it never names an alternative.

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 by the content description but no explicit when-to-use or when-not-to-use guidance is given, and no sibling is referenced. An agent can infer this is the profile lookup, but must decide on its own when to prefer search instead.

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

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

Annotations already declare the safety profile (readOnly, idempotent, non-destructive), so the description's job is to add behavioral context — which it does: deterministic newest-first ordering and the fact that the response also carries the available topic list. It omits pagination/limit truncation behavior, which is the remaining gap.

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?

A single tight sentence pair: what is listed, in what order, what fields, then the optional filter. Ordering and scope are front-loaded and nothing is wasted.

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 an output schema present, the description need not detail return values, yet it still names them, and it covers filtering and ordering. The only missing piece for correct invocation is any hint about result-set size or the limit default.

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 both limit and topic. The description only echoes the topic filter and never mentions the limit parameter or its default, so it adds little beyond the structured fields — the 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 ('List the essays'), plus ordering ('newest first') and the fields returned, so the agent knows exactly what comes back. It does not explicitly contrast itself with the sibling get_essay, so it falls short of the 5 bar for sibling 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?

'Optionally filter by topic slug' implies the filtering use case, and 'Omit for all essays' in the schema reinforces it. However, there is no explicit guidance on when to use this versus get_essay (single essay) or search, leaving selection 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?

Annotations already cover readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is settled. The description adds genuinely useful context beyond that: the response carries duration, purpose, and a booking link qualified as "for humans", hinting that the link may not be agent-usable.

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?

A single sentence, front-loaded with the resource and its contents. The nested parenthetical quoting ("kennenlernen" (Kennenlernen, 30 min)) is slightly clunky but each clause carries information rather than 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?

With an output schema present, the return values need no explanation here, and a zero-parameter read-only tool needs little more. The only missing element is an explicit pointer to book_meeting as the follow-up action.

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 takes zero parameters, so the schema has nothing to document and the baseline of 4 applies. The description correctly adds no parameter guidance because none 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 states the resource concretely — the catalog of bookable call types with Jan Linketscher — and enumerates examples ("kennenlernen" 30 min, "sparring" 60 min). It is distinguishable from book_meeting in content, though it never explicitly contrasts itself with the booking sibling.

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 only implied: an agent can infer this is the lookup step before calling book_meeting, but the description never states when to use it or that it must precede booking. No alternatives or exclusions are named.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds genuinely new context beyond the schema: the search corpus spans essays and certain pages, results are ranked excerpts, and German queries perform best. It stops short of mentioning rate limits or result ordering specifics.

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 short sentences, front-loaded with what is searched, then what comes back, then the one non-obvious tip. No filler, no repetition of schema or annotation 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?

For a two-parameter, read-only search tool with an output schema and full annotation coverage, the description supplies the corpus scope, return fields, and a language caveat — near complete. The main omission is guidance on using this versus the retrieval siblings.

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

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

Schema description coverage is 100% (query = 'search terms', limit = max results with default 5), so the schema carries parameter semantics. The description adds only the German-language tip for query phrasing, and says nothing about limit or why one would tune it, so the 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 (full-text search) and resource scope (all essays and pages, noting 'about' and 'context'), and the return shape (title, URL, snippet). This clearly separates it from siblings like get_essay and list_essays, which retrieve by identity rather than by query.

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 ('full-text search across all essays and pages') and adds a practical hint that German queries work best, but it never states when to prefer this over get_essay or list_essays, nor any exclusions. Usage is inferable but not guided.

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