Rafał Doniec: AI for companies

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

Goes beyond annotations by disclosing side effects: Rafał receives the request and the client gets a draft offer by e-mail. It also states the one-request-per-address-per-day limit, which is important for a non-idempotent mutation; remaining error/permission details are left to annotations/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?

Three tightly written sentences: confirmation action, side effects, and daily rate limit. Each sentence adds useful information and the action is front-loaded.

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

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

For an 8-parameter mutation with nested answers, full schema coverage, annotations, and an output schema, the description supplies the key behavioral context (side effects and rate limit). Together with the title and token description, it is sufficient for an agent to call 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 all eight parameters are documented in the schema. The description only highlights the 6-digit code and does not add format or constraint details beyond the schema, making baseline 3 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 ('Confirms') and resource ('quote request') with the 6-digit code, and the title/description mark it as step 2. This distinguishes it from request_quote, which initiates the flow.

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?

Gives clear context: it is used once the client has received the 6-digit code. It does not explicitly name request_quote as the prerequisite or state when not to use it, so routing relies partly on the title and token parameter description.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: the calculation is deterministic (price list in code, matching the site assistant), the draft offer is conditional on all five answers, and MCP Apps hosts render an offer card.

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 compact sentences, front-loaded with what the tool returns, then the computation source, then the conditional offer behavior. Nothing is wasted, though the phrasing is dense and slightly awkward ('what the price is made of').

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 values need not be re-explained, and annotations cover the read-only profile. The description is complete enough for a 4-parameter tool with nested answers, the remaining gap being the absence of any explicit comparison to the quote-request 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%, so the schema already documents service, answers, language and description in detail. The description adds only a marginal nuance — that a complete five-answer set changes the output — without clarifying parameter formats or the link between answers and pricing tiers.

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 the concrete outputs (net price range in PLN, monthly upkeep, duration, price breakdown) for a service plus its answers, which is specific enough that an agent can distinguish it from get_quote_questions or request_quote. It is clear what the tool computes, though it never explicitly states the verb or names a sibling it is not.

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 context — the estimate comes from the same price list as the site's quote assistant, and a draft offer appears once all five answers are supplied — but it never states when to use this instead of request_quote or confirm_quote. Usage is implied rather than routed.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds content-level context (which contact channels are included), but says nothing about response shape or limits — acceptable since an output schema is present.

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 compact sentence that leads with the subject (how to reach the person) and enumerates the returned channels. No filler, though the sentence fragment style reads slightly informally.

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 parameters, read-only annotations, and an output schema handling return details, the description covers everything an agent needs: what entity it concerns and what contact information comes back.

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 there are no parameter semantics to document. Baseline 4 applies; the description cannot add or detract value here.

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 the concrete resource (contact channels for a specific person: e-mail, call booking, LinkedIn, company details) and is easily distinguished from all siblings, which are quote/service/blog tools. It lacks an explicit verb (e.g. 'Returns'), 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?

Usage is only implied: an agent infers this is the tool for 'how do I reach this person' questions. No when-not or alternative routing is stated, though no sibling overlaps this domain, so the omission is low-risk.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that the output mirrors what the site's quote assistant asks and splits the five questions into pricing vs scheduling roles, which is useful context, but says nothing about caching, rate limits, or freshness of the question 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?

Two compact sentences with no filler, and the core return content (five questions with option ids) is front-loaded. The second sentence is slightly cryptic in phrasing but earns its place by explaining the question semantics.

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

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

An output schema exists, so return-value documentation is not required, and the description does convey the shape of the result. However, for a tool that is clearly a step in a quote workflow, it omits how the returned option ids should be consumed downstream, leaving a gap an agent must bridge.

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%: both 'service' (id from list_services) and 'language' (default en) are documented in the schema with enums. The description adds no parameter-level detail beyond the schema, 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 concrete verb+resource: retrieves the five quote questions for a service, including their option ids. It is distinguishable from siblings like estimate_price or confirm_quote by the word 'questions', but it never names an alternative tool explicitly, so sibling differentiation is implicit rather than stated.

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 questions mean ('q1–q3 set the price; when and budget set the start and the follow-up') but gives no when-to-use guidance, no prerequisites, and no routing against request_quote, confirm_quote, or estimate_price. The agent must infer the workflow step on its own.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful ordering behavior ('newest first'), but says nothing about result size, pagination, truncation, or whether all posts are returned in one call.

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 sentence with zero filler, scoping information front-loaded before the ordering detail. Nothing to trim.

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

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

An output schema exists, so return shape need not be explained, and the single optional parameter plus safety hints are fully covered elsewhere. Only the absence of any volume/pagination expectation keeps it from being 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% and the single 'language' parameter is fully documented in the schema, including its enum and default. The description adds no meaning beyond the schema, which is the expected baseline here.

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 the exact resource (posts of a specific blog), its subject matter (AI in companies), and the sort order (newest first). The verb 'list' is implicit but the return set is unambiguous, and the domain clearly separates it from the quote/contact 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?

No statement of when to call this versus anything else, and no prerequisites or constraints beyond the implicit 'this returns blog posts.' The sibling tools are all quote/contact related so the domain split is inferable, but the description offers no guidance of its own.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully adds that results include net price ranges in PLN and typical durations, which tells the agent the shape of the payload, but it says nothing about ordering, filtering behavior, or that results are localized by the language parameter.

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 front-loaded sentence with no filler, and the payoff (price ranges, durations) is placed at the end where it matters. The parenthetical service list is long but genuinely informative about coverage.

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

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

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. For a simple zero-required-parameter read tool this is nearly sufficient; only the absence of routing guidance to sibling tools keeps it from being 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% for the single optional 'language' parameter, including its enum and default, so the schema carries the full burden. The description adds no information about the parameter, 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?

The description names a concrete resource (Rafał Doniec's services) and enumerates the service categories plus the data returned (net price ranges in PLN, typical duration), so an agent knows exactly what it will get back. It does not, however, distinguish itself from siblings like match_service or estimate_price, which cover overlapping ground.

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 when-to-use guidance, no statement of prerequisites, and no mention of alternatives such as match_service (find the best-fitting service) or estimate_price (price for a specific scope). The agent must infer the browsing-vs-matching distinction from the names alone.

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?

Without annotations doing the work here beyond readOnlyHint=true and openWorldHint=false, the description usefully discloses that the matching runs on deterministic code rules rather than a language model, and that the output is advisory and must be verified with the client. That is real behavioral context an agent would not learn from the schema. It stops short of 5 because nothing is said about confidence, failure modes, or fallback behavior when no service matches.

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 compact sentences with the core action front-loaded and no filler. The verification caveat earns its place, though the phrase 'the answers it mentions' is imprecise enough to cost it a 5.

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

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

An output schema exists, so return values need not be explained, and the description supplies the important caveats: rule-based determination and a client verification step. What is missing is guidance on when this tool is the right one versus its siblings in the quote workflow.

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 both parameters are already fully documented, and the description's 'in their own words' merely echoes the description param. Baseline 3 applies since the schema does the heavy lifting; the note that mentioned features are priced in adds only 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?

States a specific verb and resource: it reads the client's need and suggests a matching service. The phrase 'the answers it mentions' is vague about what secondary output is produced, and the description does not distinguish itself from siblings like estimate_price or list_services, 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?

There is no explicit when-to-use guidance, no condition selecting this tool over estimate_price or list_services, and no statement of prerequisites. The only contextual hint, 'check the result with the client,' is a post-call caution rather than 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?

Annotations already declare non-readonly, open-world, non-idempotent behavior; the description adds genuinely useful context beyond that — an outbound e-mail side effect, a returned token, and that no human is notified until confirmation. It does not mention that repeated calls re-send codes or what happens to a stale token, which keeps it out of 5 territory.

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 the action and side effect, then the required next step. No filler, and each sentence carries distinct 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?

An output schema exists so return values need not be explained, and annotations cover the safety profile. What an agent still needs — the two-step flow, the e-mail side effect, and the handoff to confirm_quote — is all 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%, so the schema already documents email, service, answers, language, and company, including the get_quote_questions reference. The description adds no additional parameter meaning beyond reiterating that a code goes to the client's address, 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?

The description names a specific verb+resource (starts a quote request) and states the concrete mechanics: e-mails a 6-digit code and returns a token. It is clearly distinguishable from the sibling confirm_quote, which it explicitly names as the follow-up 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?

It gives clear sequencing guidance: call this first, ask the client for the code, then call confirm_quote with the same details. That routes the agent to the right sibling, though it never states when this tool should not be used (e.g. resuming an already-started request).

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