Multiservicios services

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

Annotations only declare the write/open-world/non-idempotent/non-destructive profile; the description adds real behavioral context: a human reviews the application, it does not list the business or promise approval, it creates no service, it returns status 'received' on success, and it must not be resubmitted. It also discloses a data-collection restriction (no document, ID number or immigration status is asked for or accepted), which no structured field conveys.

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-loads the negative scoping and alternatives, then the required intake, then the outcome warning — a sensible order with no filler sentences. The middle paragraph's enumeration of fields largely mirrors the schema, which is the only mild redundancy.

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 nonetheless flags the 'received' status the agent will see. With 10 params at 100% schema coverage plus annotations, the definition covers preconditions, intake, outcome and follow-up completely.

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 per the rubric the baseline is 3; the description earns above that by explaining how to elicit the values conversationally, how to obtain consent in the person's own words before sending consent: true, and by defining what is deliberately NOT collected. It does not add format detail beyond the schema (enum, state codes, email pattern), so it is not 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?

States a specific verb (apply) and resource (business provider application) plus the network it targets, and explicitly names the sibling it is not for: 'not for a customer looking for a service (use request_service)'. An agent can distinguish it from request_service, my_referrals and list_services without opening any 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?

Gives explicit when-to-use (a business offering its own services) and two explicit when-not-to-use cases (customer seeking service, affiliate referring customers), each with a routing alternative. It also states the prerequisite consent flow and the follow-up rule ('Do not send it again').

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 declare readOnlyHint and openWorldHint; the description goes well beyond them by disclosing what is NOT returned (no price, fee or coverage), why (the affiliate handles pricing on the phone), and the licensing relationship ('Sigo Seguros is a licensed insurance agency, not an insurance carrier'). That sets agent expectations in a way the annotations cannot.

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-loads what the tool returns and the slug handoff, then the usage rule, then the return-value disclaimer. Every sentence carries information, though the two-paragraph structure is slightly longer than strictly needed for a one-parameter lookup.

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 no explanation, and the description still adds the useful negative disclosure about pricing and coverage. For a single-enum-parameter read tool, nothing an agent needs to call it correctly 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 description coverage is 100% and the single locale parameter is fully documented in the schema, including the enum and the instruction to derive it from the customer's own messages. The description adds no parameter-level detail, so the baseline of 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 the resource precisely ('the services that are live right now') and its role in the workflow ('with the slug to pass to request_service'), which cleanly separates it from the request_service sibling that consumes its output. An agent can identify what this returns and where it fits without opening any 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?

Gives an explicit directive ('Call it before asking the customer anything') plus the condition that makes it mandatory ('a service that is not in this list cannot be requested'). It also spells out the cost of skipping it, which is stronger than typical when-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?

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, and the description usefully adds the authentication requirement (affiliate's own token) and an explicit data-boundary exclusion. It does not cover failure modes or rate limits, so not 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?

A single dense sentence, front-loaded with the resource identity followed by the scope constraint. No filler, no restatement of the title.

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 described, and the annotations plus the description's auth/scope statement cover what an agent needs to call it. Minor gap: no guidance on locale/error behavior if the token 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?

Only one parameter (locale) and schema description coverage is 100%, including a well-written enum explanation, so the schema carries the full burden. The description adds no parameter-level detail, 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 a specific resource (the affiliate's own profile) and enumerates the concrete payload fields — referral code, account state, public affiliate page — so an agent can tell it apart from my_referrals, my_earnings, and my_service_links 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?

Gives clear usage context: it requires the affiliate's own token, answers for nobody else, and holds nothing about a customer — effectively a when-not boundary against customer-facing or admin lookups. It stops short of naming which sibling to call instead for related data.

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 the safety profile (readOnlyHint, openWorldHint, destructiveHint=false). The description adds genuinely non-obvious domain behavior: rewards exist in two states and in-review rewards are not owed because a human reviews each referral. That is real interpretive context the schema and annotations do not carry, though it says nothing about pagination or freshness.

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, purpose front-loaded, the critical warning placed second. The warning sentence is somewhat repetitive ('has not been approved and is not owed... may decide against it'), but the redundancy is defensible for an error mode that would otherwise cause incorrect sums.

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 structure need not be explained. The description covers what is fetched and the one interpretation rule that matters for this tool; the locale-driven language of results is fully handled by the schema. Nothing essential for a correct call is missing, though no routing guidance against siblings is given.

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% – from/to defaults and the locale enum usage are fully documented in the schema itself. The description only echoes 'over a date range' and adds no syntax, format, or constraint detail beyond what is already there. 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 names a concrete resource and scope: 'Clicks, referrals and rewards for this affiliate over a date range, per service and in total.' An agent can tell this is the affiliate's own earnings summary rather than a provider-side operation. It does not explicitly distinguish itself from the close sibling my_referrals, which is why 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?

The only guidance is about interpreting the output ('Approved and in-review rewards are two separate numbers... Never add them together'), not about when to select this tool versus my_referrals or my_account. There is no stated trigger condition for calling it and no exclusion stated.

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 establish a safe read (readOnlyHint=true, destructiveHint=false), so the bar is lower, yet the description adds real context: every referral is human-reviewed, pending ones are not earned rewards, and customer identities are deliberately unavailable on this surface. That privacy/interpretation context is genuinely beyond 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?

Three sentences, front-loaded with what the tool returns, followed by two short caveats. Each sentence earns its place, though the final clause is slightly wordy.

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 needn't be fully explained, yet the description still flags the key returned concepts (milestone, review state) and the identity limitation. Adequately complete for a read-only list tool, with only the alternative-routing guidance 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 description coverage is 100% and all six parameters (including the three enums) are already documented in the schema, so the baseline is 3. The description adds no filter syntax or usage detail 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?

States a specific resource ('the referrals credited to this affiliate') and adds what is returned — milestone reached and review status. The 'my_' prefix plus the resource clearly separates it from sibling tools like my_earnings and my_service_links.

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 (use when the affiliate asks about their own referrals) and the 'pending is not an earned reward' note is a useful interpretive cue, but no sibling alternatives are named and no when-not-to-use condition is given.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: a switched-off service comes back as disabled and sharing it credits no referral, and the response deliberately omits price, fee and coverage. That is substantive disclosure the annotations do not carry.

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, front-loaded sentences with no filler: content first, then the disabled/credit caveat, then the explicit scope exclusion. The last sentence is slightly redundant in restating the omission ('and there is none here to look up') but it usefully kills a plausible follow-up query.

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 structure need not be spelled out, yet the description still flags the disabled-state case and the excluded fields, which are the parts of the payload an agent would otherwise misread. With safety covered by annotations and locale covered by the schema, nothing needed to call this correctly 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?

There is a single parameter and schema coverage is 100%, with the locale enum and its purpose fully documented in the schema itself. The description adds no locale-specific meaning, so this sits at the baseline where the schema does all the 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 names the resource (each service the affiliate holds) and the payload (their own referral link plus an HTML embed snippet), which is enough to separate it from the similarly named list_services and my_referrals. It never states an explicit verb such as 'returns' or 'lists', so the agent has to infer the operation from the shape of the output, but the resource and content are 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?

Usage is implied by the content described rather than stated: an agent can work out this is the tool to call when it needs embeddable referral links, and the note that price/fee/coverage are not returned signals it should look elsewhere for those. However, no sibling is named and no positive 'use this when...' condition or prerequisite is given.

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 annotations providing readOnlyHint=false, idempotentHint=true, and destructiveHint=false, the description adds crucial context beyond those clues: it explains exactly what is not done (no quoting, pricing, selling, payment, or binding), that consent is mandatory and how it must be obtained, what happens on success (status 'received', a reference), and the idempotent behavior of repeats within the same conversation — including the nuance that a genuinely failed request returns delivery_failed and isError and is worth retrying.

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 well-structured and front-loaded with purpose and boundaries, but it is somewhat lengthy. Every sentence carries useful information about consent, refusal of extra fields, and idempotency, so it earns its place, though it could be slightly 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?

Despite six parameters, a strict schema, and an output schema, the description covers all the essential behavioral and procedural details an agent needs: consent requirement, accepted fields, refusal of extra data, success response, idempotency, and retry conditions. Nothing critical 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 description coverage is 100%, so the baseline is 3, but the description adds substantial meaning beyond the schema: it clarifies that consent must be in the customer's own words, that only the service, name, phone, consent, and language are accepted, and that extra data like an address, ID number, immigration status, or date of birth is refused rather than dropped. This directly explains the additionalProperties: false and the required list.

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 (leaves the customer's name and phone number) and resource (a request for an affiliate to call about a service), and it immediately draws boundaries that distinguish it from siblings: it does not quote, price, sell, take payment, or bind coverage. Sibling tools like apply_as_provider or list_services are clearly separate.

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 explicit when-to-use prerequisites (ask for consent in the customer's own words), when-not-to-use guidance (do not call again for the same customer and service), and describes retry conditions (only when the request genuinely failed). Nothing is left to inference.

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