mcp-server

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

Annotations already cover safety hints (`readOnlyHint=false`, `destructiveHint=false`, `openWorldHint=true`), but the description adds substantial behavioral context beyond them: return statuses (`incomplete`, `invalid_slots`), link expiry after 24 hours unopened and 7-day reopen window, first-opener ownership, professional routing (24-hour head start unless `open_to_others` is true), and a privacy constraint. This is rich, non-contradictory 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?

Although long, the description is front-loaded with purpose and each sentence conveys a distinct behavioral rule, edge case, or workflow step. There is no filler or repetition; dense but necessary detail for a 13-parameter tool. Information is arranged logically from draft creation through routing, expiry, and privacy.

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 output schema, the description carries the return-value burden and does so by naming the `incomplete` and `invalid_slots` statuses and explaining the link returned on success. It also covers prerequisites, routing behavior, link lifecycle, and privacy rules. Given the tool's complexity and annotation coverage, an agent has enough context to invoke 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 coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the process behind `slots` (keyed by slot key from `muovi_get_service_requirements`, missing answers produce `status: incomplete`), the practical meaning of `professional_id` and `open_to_others` (24-hour exclusivity versus immediate opening), and the fallback to `professional_slug`. Some fields such as `title`, `budget_amount`, and `zone_text` add little beyond their schema descriptions, so it does not reach a full 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?

The description opens with a specific verb and resource: 'Save a task draft on Muovi' and 'get back a link.' It immediately distinguishes this tool from publishing ('This tool publishes nothing and does not notify any professional') and from the full-request workflow that requires calling `muovi_get_service_requirements` first. An agent can identify the tool's role 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?

It gives explicit when-to-use guidance: call `muovi_get_service_requirements` first, ask every required question, send answers in `slots` with `location`; use `professional_id` to direct the draft; omit both `professional_id` and `professional_slug` for a general request. It also states when `description` alone is sufficient. Alternatives and conditions are named rather than left 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 declare readOnly, idempotent, non-destructive, but the description goes far beyond by disclosing no network call and nothing saved, and by explaining the 24-hour exclusivity window and the option to receive other offers immediately. This is meaningful behavioral context an agent cannot get from 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?

Front-loads the core action and then layers workflow and business rules efficiently. Slightly dense with multiple clauses, but every sentence earns its place and there is no 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?

For a two-parameter link builder with no output schema, the description covers inputs, workflow, business logic, and the no-side-effect guarantee. An agent has everything needed to call it and hand off the result 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 coverage is 100% and both parameters are already documented with source references in the schema. The description reinforces the source tools but adds no new syntax or format detail beyond what the schema provides, so baseline 3 is 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?

Starts with a clear verb and resource ('Build a link') and immediately scopes it to task creation for one professional and one service. It explicitly distinguishes itself from the ProSite and from the sibling draft tool by explaining the link opens Muovi's own task form.

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?

Tells the agent exactly which sibling outputs to feed in: professional_id from muovi_search_professionals and service_slug from muovi_list_services. Also clarifies the workflow — give the URL to the person who completes the task on Muovi — and states no network call is made.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful disclosure about the payload — what is returned and, importantly, that phone, email and WhatsApp are NOT returned — but says nothing about failures (invalid id, unknown slug) or whether results are cached. Decent additive context, not 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?

A single dense, front-loaded passage: identification of the resource first, then return contents, then the negative disclosure, then the hand-off to sibling tools. Every sentence carries weight and none is padding.

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 output schema, the description compensates by enumerating return fields and explicitly listing excluded PII, which is exactly what an agent needs to decide whether this call answers the user's question. Combined with the task-creation hand-off, nothing material is missing for a single-parameter read tool.

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 schema already documents both the search-sourced id and the accepted ProSite slug fallback, so the description's restatement adds little. Baseline 3 is correct when the schema fully carries parameter meaning.

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 ('Fetch the full public profile of one Muovi professional') and immediately scopes the identity of the resource to an id sourced from muovi_search_professionals. Enumerating the returned fields makes it unambiguous against siblings like muovi_get_reviews.

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 tells the agent where the required id comes from (muovi_search_professionals) and gives a follow-on routing rule: to start a task, use muovi_create_task_link or muovi_create_task_draft with this id as professional_id. This is when-to-use plus what-to-use-next, nothing left 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 the safety profile (readOnlyHint, destructiveHint=false), so the bar is lower, and the description clears it by disclosing sort order, pagination, and a privacy behavior an agent would otherwise not anticipate (surnames are redacted to 'María G.'). It does not state rate limits or empty-state behavior, but that is minor against the annotation coverage.

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, front-loaded with the operation and resource, then the derived-`id` routing rule before the field inventory. The field enumeration is long but earns its place because there is no output schema. Minor density cost from listing six fields in a single sentence.

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 output schema, the description carries the return-value burden and does so explicitly: rating range, optional title/comment, reduced author name, author role, service category, and ISO created_at. Combined with the id-sourcing rule and pagination, an agent has everything needed to call and interpret this tool.

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 `id`, `limit` (default 20, max 50), and `offset` are already fully documented in the schema, and the description adds no syntax beyond that. The only extra nuance, the accepted ProSite slug, is duplicated from the schema rather than expanded. 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?

States a specific verb and resource ('Fetch paginated reviews for one Muovi professional'), names the ordering (most-recent first), and pins the resource identifier to the sibling tool that produces it. An agent can distinguish this from muovi_get_professional or muovi_search_professionals 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 use case ('surface social proof when recommending a professional') and ties the `id` to muovi_search_professionals, which routes the agent correctly. It stops short of stating when NOT to use it (e.g., when you only need aggregate rating, which muovi_get_professional may supply), so it is clear context without exclusions.

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 destructiveHint=false, so the safety profile is covered; the description reinforces it with 'Read-only.' It adds genuinely useful context beyond the annotations: the shape of each returned slot, the `ask_if` conditional applicability, and the boundary that photos are handled by the person on Muovi rather than through this server. It does not discuss pagination or result size, which keeps it short of 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?

Purpose is front-loaded in the first clause, and every subsequent sentence carries distinct information (parameter source, output fields, feedback path, photo boundary). It is somewhat dense in the enumeration of slot fields, but nothing is redundant.

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?

There is no output schema, so the description correctly carries the burden of describing the return shape: `key`, `question_es`, `type`, `options`, `value_format`, `required`, `ask_if`, and `photo_policy`. It also closes the loop on how answers are consumed by `muovi_create_task_draft`, which is exactly what an agent needs to complete the 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% and the single parameter is fully documented, so the baseline is 3. The description's 'Pass a `service_slug` from `muovi_list_services`' restates the provenance already present in the schema description rather than adding new syntax or format detail.

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 ('List') and resource ('the questions Muovi asks for one service') and immediately frames the workflow role relative to siblings (`muovi_create_task_draft`, `muovi_list_services`). An agent can tell it apart from the other muovi_* tools 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 says when to use it ('so you can ask the person before calling `muovi_create_task_draft`') and where the required input comes from ('Pass a `service_slug` from `muovi_list_services`'). Both the trigger condition and the prerequisite source are named, leaving nothing 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 cover the safety profile (readOnly, non-destructive), and the description adds real behavioral context: slugs are stable, the response nests neighborhoods under cities, and each entity exposes slug + name. It doesn't mention pagination or what happens for unsupported locations, but for a fixed catalog read that is a minor 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?

Three tight sentences, front-loaded with what is returned and followed by the slug contract and the call condition. No filler; every sentence carries information an agent needs.

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?

No output schema exists, so the description carries the return-shape burden and does so: it names the city fields (slug, name), the nested neighborhood fields, and the stability guarantee. For a zero-param read tool this is complete enough to call and consume 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?

Zero-parameter tool, so the baseline is 4. The description goes further by explaining that the returned slug fields are the exact values expected by the `city` and `neighborhood` parameters of muovi_search_professionals, which links output semantics to downstream parameter use.

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 every Argentine city Muovi serves') plus the nesting structure (active neighborhoods under each city). A reader immediately knows this is a location-taxonomy lookup and can distinguish it from siblings like muovi_search_professionals or muovi_list_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?

Explicitly states the triggering condition: 'Call this when you need to resolve a user's location wording to a Muovi city or neighborhood slug.' It also names the downstream tools that consume the slugs, so the agent knows this is a prerequisite step rather than a terminal call.

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=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds real context beyond them — a stable slug, the requires_matricula license flag, and ecosystem guarantees (identity-verified professionals, on-platform payment, dispute resolution) — but says nothing about auth needs, caching, or rate limits.

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 verb and scope, then return shape, then the usage trigger — good ordering with no boilerplate. The long parenthetical enumeration of Spanish trade names is useful for slug mapping but is the one place the sentence sprawls.

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?

There is no output schema, and the description compensates by naming the fields returned (slug, name, optional description, requires_matricula). Combined with the zero-parameter schema and the sequencing guidance, an agent has everything needed to call this 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?

The tool takes zero parameters, so the baseline is 4. The description does add cross-tool meaning by explaining that each entry's slug is the value to pass as the `service` parameter on muovi_search_professionals and muovi_create_task_link, which is more than an empty schema conveys.

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?

Specific verb+resource (list every service category Muovi supports) with an explicit geographic scope (Argentina) and an enumerated inventory of the categories returned. It is clearly distinguishable from siblings like muovi_list_cities or muovi_search_professionals, which operate on cities and professionals rather than the service taxonomy.

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?

Ends with an explicit sequencing rule: 'Call this first when you need to map a user's natural-language request to a Muovi service slug.' It also names the downstream consumers of the returned slug (muovi_search_professionals, muovi_create_task_link), so the agent knows both when to call it and what it enables.

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?

Beyond the readOnlyHint/openWorldHint annotations, it discloses the 5-result cap, ordering rules (declared trade first, then review score, verified identity/background/matrícula weighting, other-trade businesses last), the presence of a match echo, and the privacy fact that no phone, email or WhatsApp is returned. This is behavior an agent cannot infer from structured fields.

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 required-inputs rule is front-loaded and every paragraph carries actionable content, but the middle section on ordering and verification fields is dense and slightly repetitive for a single tool description. Still efficient enough to justify its length given the absence of an output schema.

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 output schema, the description fully documents the return shape (match, rating, review_count, verifications, up to 3 portfolio URLs, id, profile_url) and the next-step workflow, so an agent has everything needed to call the tool and act on the result.

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 adds real semantics: it ties service and neighborhood to their slug-producing tools and to the requirement to ask the user when missing, and explains city's optional disambiguation role implicitly. The has_matricula and verified_identity filters are left to the schema, so it does not fully compensate beyond baseline.

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 opens with a precise verb+resource+scope: find up to 5 professionals for one service in one barrio. It clearly separates this from siblings such as muovi_get_professional (full profile) and muovi_create_task_draft (next step), so an agent can route correctly without reading 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?

It states both required inputs and their slug sources, instructs the agent to ask the user before searching when service or barrio is unknown, and explicitly routes post-search follow-ups to muovi_create_task_link, muovi_create_task_draft (with or without professional_id) and muovi_get_professional. Alternative conditions are spelled out rather than implied.

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