mcp-server

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

Annotations only declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true. The description goes far beyond them: it discloses that nothing is published or notified, that incomplete/invalid input returns status 'incomplete' or 'invalid_slots' with no link, that an unopened link expires in 24 hours, that the first opener takes the draft and can reopen for 7 days, and that contact details must be excluded.

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 purpose and the publish-nothing guarantee are front-loaded, and nearly every sentence carries operational information for a 13-parameter tool. It is a dense, run-on paragraph without headings or bullets, which hurts scannability, but little of the content is 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?

For a complex 13-parameter mutation with no output schema, nested objects, and an interactive collection workflow, the description covers prerequisites, the interactive ask-loop, error statuses, link lifecycle, and privacy constraints. An agent has essentially everything needed to drive the flow 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, but the description adds real meaning: professional_id vs professional_slug equivalence, that open_to_others controls whether the chosen professional gets a 24-hour head start, that slots are keyed by slot key from muovi_get_service_requirements, and that a 'flexible' urgency needs no date.

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 states a precise verb and resource ('Save a task draft on Muovi ... and get back a link') and immediately clarifies the crucial distinction that it publishes nothing, which separates it from a link/publication flow. An agent can tell what this tool does and what it does not do 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?

The description routes the agent explicitly: call muovi_get_service_requirements first and collect its fields, use muovi_list_services for service_slug, muovi_search_professionals for professional_id, and leave both professional fields out for a general request. It also gives when-to-use rules for open_to_others and the one-question-per-message protocol.

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?

Beyond the readOnly/openWorld annotations, the description discloses what is returned field-by-field, what is deliberately withheld (phone, email, WhatsApp), and a non-obvious presentation rule about only naming verified checks and never flagging a missing one. This is exactly the kind of behavioral context annotations cannot 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?

The return payload is front-loaded, followed by exclusions, presentation guidance, and next-step routing, and each sentence carries distinct information. It is on the long side, but no sentence is 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 no output schema, the description fully compensates by enumerating the returned fields and the intentionally omitted contact data, plus the downstream tool for starting a task. An agent has everything needed to call and use 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 the schema already documents the id and the ProSite-slug fallback, so the description adds little new parameter meaning beyond restating provenance. Baseline 3 is appropriate 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 (Fetch) and resource (the full public profile of one Muovi professional), scoped to a single entity, which cleanly separates it from muovi_search_professionals. It even names the upstream source of the id, so an agent knows exactly which tool produces the input.

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 explains the id's provenance (muovi_search_professionals) and routes the next step to muovi_create_task_link / muovi_create_task_draft with the same id, which is clear contextual guidance. It does not state an explicit when-not-to-use case, so it stops short of the top tier.

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, destructiveHint=false, and openWorldHint=true, and 'Read-only.' is consistent with them. Beyond that it discloses genuinely useful behavior: photos are added by the person on Muovi (not through this server), the address is confirmed on Muovi's map, and `photo_policy` indicates whether photos help. It stops short of describing any rate limits or error behavior, and much of the text is workflow rather than tool behavior.

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 and routing are front-loaded, but the body sprawls across several concerns (slot field anatomy, collection protocol, urgency exception, photo policy, address confirmation) without separation, and repeats the `slots`/`description` destination more than once. Every idea is relevant, but the framing as one long paragraph makes it harder to scan.

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 enumerating the returned slot shape (`key`, `question_es`, `type`, `options`, `value_format`, `required`, `ask_if`) and the `photo_policy` field. Combined with the routing to `muovi_create_task_draft` and the field-validation guidance, an agent has everything needed to call and consume 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?

A single parameter with 100% schema coverage and an example value in the schema gives a baseline of 4. The description adds that the slug must come from `muovi_list_services`, which is the one piece of selection meaning the schema string alone doesn't convey.

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 gives a specific verb and resource ('List the fields Muovi takes for one service') and explicitly positions it relative to siblings by naming `muovi_create_task_draft` as its consumer and `muovi_list_services` as the source of the slug. An agent can distinguish it from every other muovi_* tool without opening a 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?

Explicit sequencing is given: read this before calling `muovi_create_task_draft`, obtain the slug from `muovi_list_services`, ask one question per message and wait for the answer, and treat `flexible` urgency as complete without a date. It also states what not to do (don't ask optional slots as a list) and where the address/photo steps live.

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?

Annotations already establish read-only and open-world, and the description adds substantial context beyond them: the 3-page pagination ceiling, result ordering (declared trade first, then review score, other-trade businesses last), the exact return fields, and the explicit absence of phone/email/WhatsApp. It also discloses behavioral constraints an agent could otherwise violate, such as never stating how many professionals exist and never saying a check is unverified.

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 and preconditions are front-loaded and most of the length is justified because there is no output schema, so field and ordering details must live here. It is nonetheless a dense block that mixes invocation guidance with presentation policy, and a few lines (e.g. how the card view renders photos) add little for the calling agent.

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 and a 6-parameter search, the description carries the full burden and does: required inputs, result fields, ordering, pagination semantics, presentation rules and next-step tool routing. An agent has everything needed to call it correctly and to handle both the has_more and no-more-results cases.

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 every parameter, including the slug sources (muovi_list_services, muovi_list_cities) and the page/has_more relationship. The description largely restates those dependencies rather than adding new meaning, and it never mentions the has_matricula or verified_identity filters or when to use the optional city override, so it does not exceed the 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?

Opens with a specific verb, resource, page size and scope: 'Find up to 5 Muovi professionals per page for one service in one barrio.' It also names the sibling boundary explicitly at the end ('Use muovi_get_professional with the id for the full profile'), so an agent can distinguish search from profile retrieval without opening either 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 rules and preconditions: both slugs are required and the agent must ask the user which service and barrio if unspecified. It also routes to concrete alternatives after results (muovi_create_task_link, muovi_create_task_draft with or without professional_id) and handles the has_more=false case with a named fallback rather than a dead end.

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