MoeGo MCP by usefulapi

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

Goes well past the annotations by disclosing the key behavioral trait of a write tool with no idempotency guarantee: it appends a new note on every call, never replaces or deletes, and must not be retried blindly after a timeout. It also names the underlying endpoint (POST /v1/customers/{id}/notes), giving the agent a model of the side effect it is triggering.

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 WRITE marker and the core action, followed by the non-idempotency warning and then the endpoint. Nothing is padded and the most decision-relevant fact (every call adds a note) appears early.

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 write tool with no output schema, the description covers the action, side-effect semantics, retry hazard, and endpoint. What it lacks is whether notes are visible to customers vs. staff-only, any required permission scope, and what the call returns — minor gaps but relevant to an agent deciding whether to invoke it.

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 50% — only `note` is documented in the schema, and `customer_id` is bare. The description implies `customer_id` targets a customer profile and that `note` is staff-authored text, but it adds no format, length, or identification detail (ID vs. external ID) beyond what the schema already conveys. A 3 reflects that 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?

"WRITE: add one staff note to a customer profile" gives a specific verb (add) and resource (staff note on a customer), and the "WRITE:" prefix plus the append-only phrasing separates it from the read-side moego_list_customer_notes sibling. An agent can identify this as the create-side note tool 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 redirects to moego_list_customer_notes after a timeout, which is a concrete when-not/alternative pairing. It does not, however, say when an agent should add a note at all or how this relates to other write operations on a customer, so the guidance is situation-specific rather than complete.

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?

readOnlyHint=true already tells the agent this is a safe read, and the description's only extra is the raw endpoint (POST /v1/reports/data:fetch), which is marginal. It says nothing about pagination behavior, whether period is mandatory, or how large a result set can be.

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 tight sentences with the purpose front-loaded and no filler. The API endpoint sentence is low value for an agent but does not bloat the definition.

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 8 parameters, no output schema, and vague phrasing like 'table data', the agent has no idea what the returned rows/columns look like or how grouping affects output. It is callable from the schema but the return contract is undefined.

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 88%, so the schema already carries parameter meaning (report_id provenance, obfuscated ids, RFC 3339 dates, page_token semantics). The description adds nothing beyond that, which is the baseline case.

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+resource: fetching the table data of one report for a time period. This clearly separates it from moego_list_reports (which enumerates reports) without naming that sibling explicitly.

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 phrase 'for a time period' implies period_start/period_end should be supplied, but there is no explicit when-to-use guidance and no mention of when not to use it or what alternative to pick. Usage must be inferred from the params and the sibling list.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds genuine behavioral value by listing what the payload includes (pets, services, staff, times, amounts), but says nothing about not-found behavior, whether business_id must match the appointment, or payload size. With annotations covering safety, a 3 fits.

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 tight sentences with the resource description front-loaded and the raw endpoint appended as a useful reference. 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?

With no output schema, the description partly compensates by naming the fields bundled into the response. But it leaves an undocumented required parameter and gives no failure semantics, so it is only adequate for a two-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 coverage is only 50%: business_id has a description of its own, but the required appointment_id is undocumented in the schema. The description only echoes the path template '{id}' and never explains what appointment_id is, nor whether business_id is required, optional, or merely a scoping/tenant id. It does not compensate for the coverage gap.

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 ('Get') and resource ('one appointment') and enumerates the returned sub-resources, which separates it from the many list_* siblings. It never names moego_list_appointments as the sibling it is not, so differentiation is implied by the word 'one' 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?

Usage is implied: fetch a single appointment by id, presumably after seeing it in moego_list_appointments. There is no explicit when-to-use, no exclusion of alternatives, and no note about what to do when the appointment id is unknown or the appointment does not exist.

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?

The description largely restates the readOnlyHint annotation ('Read only: it books nothing'), which earns little credit beyond structured fields, though it does add the endpoint POST /v1/online_booking/availability. It discloses nothing about result limits, date-range caps, or whether availability is affected by blocks, staff schedules, or business hours.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the purpose front-loaded and zero filler; the read-only caveat and endpoint are appended efficiently.

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 six parameters (four required), half the schema undocumented, and no output schema, the description should explain what the optional filters do and what shape 'dates and times' takes. As written, an agent cannot tell how staff_ids or service_ids affect the response or whether a wide date range is permitted.

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 only 50%: business_id, staff_ids, and service_ids have no descriptions, and the tool description supplies no meaning for any of the six parameters. It neither explains that staff_ids/service_ids narrow results nor clarifies the difference between company_id and business_id.

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 — 'Get the dates and times that clients can book online for a location' — so the agent knows this returns bookable availability, not existing bookings. No sibling tool covers availability, so differentiation is implicit rather than stated, which keeps it 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 clause 'Read only: it books nothing' usefully distinguishes this from any booking-creation path, but there is no explicit guidance on when to call this versus list_appointments or get_appointment, nor any stated prerequisites for the required IDs.

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, so the safety profile is covered. The description adds the concrete API route and clarifies that the id is an obfuscated token rather than a numeric key, but says nothing about failure behavior (missing/unknown id) or what the response contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, identity and scope front-loaded, endpoint appended as supporting detail. Nothing wasted and nothing buried.

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

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

For a single-entity fetch with no output schema, the description leaves the return payload completely unspecified — the agent cannot know whether to expect address, hours, or nested location settings. It is adequate for invocation but incomplete for planning downstream use.

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% with a single parameter already described as 'Obfuscated business id', so the description merely echoes the schema's wording. Baseline 3 applies since the schema does all the semantic work and the description adds no format or sourcing 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 and resource ('Get one business location') with a clear scope ('one', 'by obfuscated id'), which distinguishes it from moego_list_businesses and moego_get_company. The endpoint string reinforces exactly what it retrieves, though it doesn't explicitly name the list sibling as the way to discover ids.

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 'by obfuscated id' — the agent infers it must already hold a business id — but there is no explicit when-to-use, no prerequisite (where the id comes from), and no named alternative such as moego_list_businesses.

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, so safety is covered. The description adds useful behavioral context by naming the underlying endpoint (GET /v1/companies/{id}) and the fields returned, but it says nothing about error behavior for invalid/obfuscated ids or auth requirements.

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 terse sentences, purpose first, technical endpoint second — no filler whatsoever.

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

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

For a single-resource read with annotations covering safety, the description is nearly complete, and enumerating returned fields partly compensates for the missing output schema. It could still say what happens on a bad id or whether the obfuscated id must come from list_companies.

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?

With one parameter and 100% schema description coverage, the schema fully documents company_id including its provenance. The description adds no parameter-level meaning beyond that, 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 specific verb and resource: 'Get one company', listing the returned fields (name, country, time zone) and the endpoint. It implicitly contrasts with the sibling moego_list_companies by emphasizing 'one', so an agent can distinguish single-fetch from listing 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?

There is no explicit statement of when to use this tool versus moego_list_companies or other get_* siblings, and no prerequisites are given. The only routing hint ('from moego_list_companies') lives in the schema's parameter description, not the tool 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?

readOnlyHint=true already declares this a safe read, so the description's main added value is telling the agent what data comes back (contact info, addresses, notes, tags, preferences). It does not say what happens when the id is unknown or whether related collections are truncated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler, and the resource scope is front-loaded before the endpoint detail. Nothing is repeated or padded.

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 burden of describing the return shape, and it does so at a useful level of detail. Missing only edge-case behavior (not-found, large note/tag lists), which keeps it short of a 5.

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 and schema description coverage is 100%, so the schema already defines customer_id as an 'Obfuscated customer id.' The description adds nothing beyond that, which is the expected baseline when the schema does 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?

States a specific verb and resource (get one customer) and enumerates what the payload contains (contact data, addresses, notes, tags, preferences), plus the underlying endpoint. The word 'one' implicitly separates it from moego_list_customers, but no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer it is for fetching a single known customer by id. There is no statement of when to prefer it over moego_list_customers or moego_list_customer_notes, and no prerequisites or failure conditions.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description carries a lower burden, but it adds nothing beyond the endpoint path — no note on errors for missing IDs, permissions, or lookup semantics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the purpose front-loaded and zero filler. Appropriately sized for a trivial one-parameter getter, though the endpoint line borders on 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?

With no output schema and no annotations beyond readOnlyHint, the description never indicates what a lead object contains or how a not-found case behaves. For a retrieval tool, that leaves meaningful gaps.

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 0% for the single lead_id parameter. The endpoint template "{id}" weakly signals that lead_id is a path identifier, but gives no format, source, or validity guidance to compensate for the undocumented schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Get one lead") plus the underlying endpoint, and the word "one" implicitly separates it from the sibling moego_list_leads. It is clear but does not explicitly name or differentiate against alternatives.

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 guidance on when to use this versus moego_list_leads or how a lead_id is obtained. The only cue is that it retrieves a single record, which an agent must infer from "one".

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds context about what the response contains (totals, tips, tax, discounts) and the endpoint, which is modest but real added value. It says nothing about error behavior for a missing/invalid id.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with what is returned, followed by the API path. No 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 simple single-parameter read tool with readOnlyHint and no output schema, the description covers purpose, returned fields, and endpoint adequately. Minor gap: no note on what happens when the order does not exist.

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 (order_id) with 0% schema description coverage, so the description must compensate. The '/v1/orders/{id}' path does imply order_id is the order identifier used as a path segment, which is some help, but format/validity of the id is never clarified.

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 ('Get one order') plus an enumeration of the content returned (totals, tips, tax, discounts) and the underlying endpoint. It implicitly distinguishes itself from the many sibling list_* tools (e.g. moego_list_orders) by saying 'one order', but never names an alternative explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the singular 'one order' plus the path template suggest it is for fetching a single known order rather than listing. There is no explicit statement of when to pick this over moego_list_orders or what prerequisites (a valid order id) are needed.

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?

readOnlyHint=true already declares the safety profile, so the description's remaining job is context. It adds useful detail about which fields come back and the REST endpoint, but says nothing about behavior on a missing/invalid ID, permissions, or error responses.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the payload summary followed by the endpoint. No filler or 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 single-parameter read tool with a readOnly annotation and no output schema, this covers purpose, returned fields, and endpoint. Only the behavior on a nonexistent payment is missing, which is a minor gap.

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 0% — payment_id has no description at all. The endpoint template /v1/payment/{id} implies the parameter is the payment identifier, which partially compensates, but format (numeric vs. opaque string) and sourcing of the ID remain undocumented.

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 ('Get one payment') and enumerates the fields returned (method, status, fees, refunds), plus the underlying endpoint. The singular 'one' implicitly distinguishes it from moego_list_payments, but it never names that sibling explicitly.

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: 'one payment' plus the /v1/payment/{id} path tells the agent it needs a known payment ID, so listing vs. fetching is inferable. There is no explicit statement of when to prefer this over moego_list_payments or what to do when the ID is unknown.

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?

While the annotations confirm it is readOnlyHint: true, the description adds behavioral context by revealing the specific data payload returned (vaccinations, vet, notes, etc.). This helps the agent understand the nature of the call beyond simple status.

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 definition is highly concise, providing the purpose and the technical endpoint structure (API path) without unnecessary 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?

Given the strong input schema and the inclusion of the full API path and attribute list in the description, the definition is complete enough for an agent to successfully select and invoke the 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?

Since schema coverage is 100%, a baseline of 3 applies, but the description adds value by detailing the specific set of attributes (breed, weight, codes) that the resulting pet object will contain.

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 uses a specific action ('Get one pet') and defines the resource being retrieved, immediately distinguishing it from list or search 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?

The usage is strongly implied by the singular 'Get one pet' and the requirement of both a customer and pet ID, but there are no explicit instructions contrasting it with 'moego_list_pets' or other get methods.

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?

readOnlyHint=true already declares this a safe read, so the bar is lower. The description usefully clarifies that results are templates rather than executed/signed agreements, but it says nothing about pagination behavior, default ordering, or result shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the core purpose. The endpoint string adds minimal value for an agent but is compact and harmless.

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 only a readOnly annotation, the description is barely sufficient: it never mentions that results are paginated (page_size/page_token) or what an agent should do with the returned nextPageToken. Adequate to call, incomplete for using the result well.

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 four parameters are already documented in the schema, including token chaining and business filtering. The description adds no parameter-level meaning beyond that, 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 specific verb and resource ('List agreement templates') and disambiguates the resource as 'contracts and waivers,' which an agent couldn't infer from the name alone. It doesn't explicitly differentiate from the many sibling list_* tools, but the resource is distinct enough to select correctly.

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 guidance on when to use this versus alternatives, no prerequisites stated, and no note that company_id comes from moego_list_companies (that detail lives only in the schema). The only usage hint is the implied 'list templates' semantics.

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?

readOnlyHint=true already covers the safety profile, so the description's main added value is the note that the operation is a POST endpoint despite being a read/list — useful counter-intuitive context. It still omits pagination/result-size behavior and whether notes are ordered or limited.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, purpose front-loaded, no filler. The endpoint line is compact and carries real information about the transport method.

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 one-parameter read tool with annotations covering safety and no output schema, this is close to adequate, but the agent still doesn't know the shape or volume of returned notes or whether the list is paginated.

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 0% for the single parameter appointment_id, so the description must compensate. "Of one appointment" implies the parameter's role but doesn't name it or add format guidance, leaving a small but real gap.

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 the notes") with explicit scope ("of one appointment"), which cleanly separates it from the sibling moego_list_customer_notes. It stops short of stating anything about filtering or result size, but the core purpose is 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?

No indication of when to choose this over moego_list_customer_notes or moego_get_appointment, and no stated prerequisites (e.g. that a valid appointment_id is required). Usage is only inferable from the scope phrase.

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?

readOnlyHint=true already establishes the safety profile, so the description's job is lighter. It adds the underlying endpoint (POST /v1/appointments:list) and confirms time formatting, but says nothing about result ordering, pagination behavior, or result-size limits even though page_token/page_size exist.

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 purpose followed by filters and format note; nothing is padded. The trailing API endpoint line is the only sentence of debatable value, though it aids debugging.

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 10 parameters, no output schema, and no annotations beyond readOnlyHint, the description should explain the paginated result shape and how to iterate pages. It covers filtering adequately but leaves return structure and paging semantics to the caller's inference.

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 70%, so most parameters are self-documenting. The description names the main filter groups (start time range, status, customers, pets) and the RFC 3339 format, but omits business_ids, updated_after, and the paging parameters, adding only marginal meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ("List appointments of a company") and enumerates the filter dimensions, so it is clearly a filtered-list tool rather than a single-record fetch. It does not explicitly name how it differs from moego_get_appointment or moego_list_appointment_notes, which keeps it off 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 description only says what can be filtered; it never states when to reach for this tool versus moego_get_appointment (single record) or the notes lists, and offers no guidance on paging through large result sets. Usage must be inferred entirely from the tool name.

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?

readOnlyHint=true already covers the safety profile, and the description reinforces it with 'blocked (not bookable)' semantics plus the concrete endpoint POST /v1/blocks:list. It adds nothing about pagination behavior, result ordering, or what a block record contains — acceptable, but lean given annotations carry the main load.

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 meaning of the resource front-loaded and the endpoint as trailing detail. Nothing wasted, nothing buried.

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, and the description never indicates what is returned (block fields, nextPageToken for paging through results) even though page_token is a parameter. For a 6-parameter list tool this leaves a real gap, though the read-only nature and schema coverage limit the harm.

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 every parameter including company_id provenance, RFC 3339 date bounds, business_ids, and page_token is documented in the schema. The description adds no filter semantics (e.g., whether start_after/end_before are inclusive), 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?

Specific verb+resource ('List blocked (not bookable) time slots') and it clarifies what a 'block' means via the staff-days-off example, which disambiguates an otherwise opaque term. It doesn't differentiate from near-neighbors like moego_get_booking_availability or moego_list_appointments, 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?

No guidance on when to call this versus alternatives — an agent checking whether a slot is free could plausibly reach for moego_get_booking_availability, and the description never routes it. No prerequisites or exclusion conditions are 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?

readOnlyHint=true already covers the safety profile, so the bar is lower. The description adds that results carry address and contact data and discloses the underlying endpoint (a POST used for listing, which is non-obvious), but says nothing about pagination behavior or total counts.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, scope first and the endpoint detail second; nothing is buried. The endpoint string is marginally useful metadata rather than filler, so only minor trimming is possible.

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 does partially compensate by naming the returned fields (address, contact data). However, it omits pagination semantics for a tool whose only optional params are paging controls, leaving the iteration contract implicit.

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 page_size, company_id and page_token are all documented in the schema. The description only repeats that the listing is scoped to a company; it adds no format or usage nuance beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List the business locations of a company') and clarifies that 'business' means location, which disambiguates from siblings like moego_get_company. It does not explicitly distinguish itself from moego_get_business, but the list-vs-get distinction is conveyed by the verb.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer this is the paged enumeration tool for companies' locations, but the description never says when to prefer it over moego_get_business or how to iterate pages. No exclusions or prerequisites are 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?

Adds real context beyond readOnlyHint=true: the return contains obfuscated company ids consumed by other tools, and the underlying endpoint is POST /v1/companies:list — useful because a POST verb might otherwise suggest a mutation. It does not mention pagination defaults or result ordering.

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, no filler, and the 'call first' prerequisite is front-loaded before the API path.

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-param read tool with no output schema, it covers purpose, prerequisite ordering, and the key return value (company ids). The shape of the returned company objects and paging behavior are left implicit, a minor gap.

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 both parameters (page_size, page_token) are already documented in the schema; the description adds nothing about paging. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource with scope: 'List the companies the API key can access.' That clearly separates it from the singular moego_get_company, though it never contrasts itself with the close sibling moego_list_businesses.

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?

'Call first: it returns the obfuscated company ids that every other tool needs' gives explicit ordering plus the dependency reason, so an agent knows both when to call it and why it must precede other tools.

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?

The annotations already state readOnlyHint=true, and the description adds the concrete API endpoint and confirms the resource is staff notes. It does not describe pagination behavior or ordering, and the POST endpoint could create minor read/write ambiguity, though the ':list' suffix and readOnly annotation reconcile it.

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 with the purpose front-loaded and no filler. The API endpoint adds concrete context without bloating the definition.

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 simple read-only list tool with one required parameter and no output schema, the description covers what is listed and the endpoint. However, it omits usage routing against siblings and does not explain pagination flow, so it is adequate but not 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 67%: page_size and page_token are documented in the schema, while customer_id is not. The description adds only that the operation is on a customer and shows {id} in the endpoint path, which partially compensates but does not clarify customer_id format or pagination semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'List' the 'staff notes on a customer.' This is clear enough to know what the tool retrieves, though it does not explicitly distinguish the scope from siblings like moego_list_appointment_notes or moego_append_customer_note.

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 guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The agent must infer that this is for reading customer notes rather than appending one or listing appointment notes.

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, so the safety profile is covered, and the description correctly stays consistent with it despite the POST endpoint (an API convention, not a mutation claim). It adds nothing about pagination, result ordering, or empty-result behavior, which is the remaining gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the purpose, followed by the concrete API mapping. No filler, though the endpoint line is closer to implementation trivia than agent-facing guidance.

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 one-parameter read tool with annotations covering safety, the definition is nearly sufficient. With no output schema, it would help to say what a pet record contains or whether results are paginated, and it gives no hint about handling an invalid customer_id.

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 0%, so the description must carry the load; it does so minimally by showing customer_id as a path parameter in the endpoint template. It does not state the ID format or where a caller obtains a valid customer_id.

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 ('pets of one customer'), and the endpoint template clarifies the customer-scoped nature. This implicitly separates it from the broader sibling moego_list_pets, though that sibling is never named explicitly.

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 phrase 'of one customer' implies this is the tool to use when you already have a customer_id and want only that customer's pets, versus the unscoped moego_list_pets. However, there is no explicit when-to-use/when-not guidance or reference to alternatives.

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?

The readOnlyHint=true annotation already establishes this as a safe read, and the description is consistent with it. It adds the underlying endpoint (POST /v1/customers:list) and the filter semantics, but says nothing about pagination behavior, ordering, or result volume beyond what the schema's page_size/page_token imply.

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; the resource and filters come first and the endpoint last. Slightly more efficient than needed but nothing wasted.

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

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

A six-parameter read tool with full schema coverage and a readOnlyHint needs little more, but the description omits what the response contains (customer objects) and any pagination guidance for following nextPageToken. Adequate, not 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%, so every parameter is already documented, giving a baseline of 3. The description only restates the phone and updated-time filters and adds no format nuances 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 verb and resource ('List pet-parent customers of a company') and names the two filter axes. It is clearly distinct from moego_get_customer and from moego_list_pets/leads, though it never explicitly contrasts with the nearest sibling list tools.

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 indicates which filters exist (phone number, last update time), which implies usage, but it never says when to prefer this list over moego_get_customer (single lookup) or moego_list_leads. No exclusions or prerequisites stated; the company_id provenance hint lives in the schema, not the 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's barrier is low. It adds the underlying endpoint (POST /v1/customers/{id}/tags:list), which usefully explains the POST-but-still-a-read pattern, but says nothing about return shape, pagination, or empty results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the purpose front-loaded and no filler. The raw endpoint line is marginally useful (it explains the POST verb) but is closer to vendor metadata than agent guidance.

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 no annotation about returns, the description should say what a 'tag' looks like (name only, id + name, ordering). It stops at the endpoint, leaving the return value unspecified for a low-complexity tool where that would have been cheap to include.

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 0% for the single customer_id parameter, so the description carries the burden. It hints at the role via '{id}' in the path, mapping it to the customer, but never states the expected ID format or that it is a customer identifier.

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 the tags on a customer' clearly states the operation and its target. No sibling tool covers customer tags, so differentiation is implicitly clear, though the description never says so explicitly.

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 by the verb 'List' and the scoping to a customer. There is no statement of when to choose this over moego_get_customer or moego_list_customers, and no prerequisites (e.g., whether the customer must exist or permissions required).

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, so the safety profile is covered. The description adds only the raw endpoint path, which is not meaningful behavioral context for an agent; it says nothing about pagination behavior, result volume, or ordering beyond the 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?

Two short sentences with the purpose front-loaded. The trailing API endpoint line is low-value for an agent but not enough to be considered bloat.

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?

This is a simple read-only list tool with a fully documented three-parameter schema and no output schema. The description covers the essential purpose; only pagination workflow guidance is missing, which the schema largely compensates for.

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 three parameters, including the page_token chaining hint, are already documented in the schema. The description adds no additional meaning, which is the expected baseline when the schema does 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?

States a specific verb and resource ('List the discount codes of a company'), which is unambiguous and distinct from siblings that list other resources. It does not explicitly contrast with a sibling, but none of the listed siblings overlap, so differentiation is implicit.

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 indication of when to use this tool versus alternatives, no prerequisites beyond company_id being required, and no note about pagination workflow despite page_token being available. Usage is only inferable from the verb 'List'.

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?

The readOnlyHint annotation already establishes the safety profile, so the bar is lower. The description adds the underlying endpoint (POST /v1/leads:list), which is mildly useful given a POST verb on a read operation, but it says nothing about pagination behavior, result limits, or what a lead record contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the purpose stated first and no filler. The endpoint reference is the only marginal sentence, though it does explain why a list operation is a POST.

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 four-parameter list tool with no output schema, the description omits what a lead object contains and how paging terminates, which an agent needs to consume results. Annotations cover the read-only safety profile, but the return shape remains undisclosed.

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 75%, with page_size, company_id, and page_token documented in the schema itself; only phone_number is undocumented. The description adds no parameter meaning beyond the schema, 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 gives a specific verb and resource ("List sales leads") and disambiguates the domain term by glossing leads as "potential customers." It does not distinguish this from the sibling moego_get_lead (single-lead fetch) or moego_list_customers, so it stops short of full sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this rather than moego_get_lead or moego_list_customers, and no prerequisites mentioned (e.g., that company_id comes from moego_list_companies, which only appears in the schema). Usage is implied by the tool name 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?

readOnlyHint=true already tells the agent this is a safe read, so the description need not restate that. It adds the underlying API route (POST /v1/memberships:list), which is marginal context, but says nothing about pagination behavior, result counts, or empty-result handling despite exposing page_size and page_token.

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 fragments with no filler; the purpose is front-loaded first. It is arguably too terse rather than bloated, and the API route is placed last, which is reasonable.

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 simple read-only list tool with no output schema and a mostly documented schema, this is close to sufficient; the main omission is any hint that results are paginated and that page_token should be followed until exhausted, which matters because required company_id scoping is already covered by the schema.

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 75%, so most parameters are already documented, including the critical company_id provenance hint. The description's 'Filter by name' loosely maps to name_like, but that parameter has no schema description, so the description adds only partial clarity on matching semantics (substring? exact? case-sensitive?).

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 and resource ('List membership plans'), matching the title exactly. It does not, however, distinguish this from the closely named sibling moego_list_membership_subscriptions, leaving an agent to infer the difference between plans and subscriptions from the name alone.

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 usage hint is 'Filter by name', which describes a capability rather than a condition for selecting this tool. No when-to-use, when-not-to-use, or alternative tool (e.g. membership subscriptions) is named.

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

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

readOnlyHint=true already declares this as a safe read, so the description owes only supplementary context. It adds nothing about pagination behavior, filter semantics, or result scope — just a restatement of the HTTP endpoint, which does not help an agent decide or call correctly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the purpose and no filler. Efficient, though the second sentence is low-value API trivia.

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 5-parameter filtered-list tool with no output schema and an undocumented pair of filter arrays, the description says far too little. An agent cannot tell what customer_ids/membership_ids do or how results are paginated.

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 only 60%: page_size, company_id, and page_token are documented, but customer_ids and membership_ids have no description at all. The description does not explain these filter arrays, so the coverage gap is unmitigated.

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 ('customer membership subscriptions'), so the operation is clear. It does not distinguish itself from the sibling moego_list_memberships, leaving the agent to infer what a 'subscription' is versus a plain membership.

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 no when-to-use guidance, no prerequisites, and never mentions the closely related moego_list_memberships sibling as an alternative. The agent gets no routing signal beyond the resource name.

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?

readOnlyHint=true already establishes the safe-read profile, so the description only needs to add context. It adds the backing endpoint (POST /v1/orders:list) and the fields returned, but says nothing about pagination behavior despite page_size/page_token existing, nor about result caps or ordering.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with what the tool returns and then the filters. The trailing API-endpoint note is minor metadata but takes little space and aids traceability.

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 is the only source of return-value information, and it gives just 'status and amounts'. It also omits pagination guidance for a 7-parameter paged list tool, leaving a meaningful gap for an agent that must page through results.

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 86%, so the schema already documents company_id, page_size, page_token, business_ids, and the RFC 3339 timestamps. The description only restates the status and update-time filters at a high level, adding no syntax or semantics beyond the schema — baseline 3.

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 orders') and clarifies the domain term by equating orders with invoices, plus names the fields surfaced (status, amounts). It does not explicitly contrast with the sibling moego_get_order (single-order fetch), but the list/singular split is implied by the name.

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?

'Filter by status or last update time' implies the retrieval scenarios but never states when to choose this over moego_get_order or moego_list_payments, nor any exclusions or prerequisites. Usage is inferable rather than guided.

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?

The description provides context by stating it lists 'packages and their usage,' which clarifies the data returned beyond the simple concept of 'packages.' This adds valuable operational context that is not contained within the schema or 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?

The definition is highly concise, using two sentences to convey function, scope, and the specific API endpoint. The sentence flow is logical and efficient.

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 list/read-only operation with a defined output structure (though not explicitly provided here), the description is complete. It clearly states the scope and provides the technical API reference, making it easier for an agent to validate the operation.

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?

Given that schema description coverage is 75% (above the 80% threshold baseline), a score of 3 is appropriate. The description reinforces the purpose of the `customer_ids` parameter by using the word 'optionally,' but does not add technical depth to the schema definitions.

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 uses specific terminology ('prepaid service packages and their usage') and a clear verb ('List'), effectively defining the resource and its action. It is clear whether the tool retrieves package definitions or package usage data.

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 indicates usage can be 'optionally for given customers,' implying flexibility. However, it fails to provide explicit guidance on when this tool is necessary compared to sibling tools (e.g., a tool that lists package prices vs. a tool that lists package usage).

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?

readOnlyHint=true already declares the safety profile. The description adds the concrete backing endpoint (POST /v1/payments:list, despite being a read) and the optional-order filtering behavior, which is mild added context but says nothing about result volume, ordering, or pagination semantics beyond the 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?

Two short, front-loaded clauses with no filler; scope comes before the API endpoint reference. Slightly redundant to append the endpoint, which adds little for tool selection.

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 read-only paginated list with no output schema, the description does not indicate what a payment record contains or whether results are ordered/filterable beyond order_ids. Adequate with schema and annotations, but leaves an agent guessing at return content.

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 75%: company_id, page_size and page_token are documented in the schema. The one undescribed parameter, order_ids, is covered by the description's 'optionally for given orders'. Baseline 3 applies since the schema does most of 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?

States a specific verb and resource ('List payments') plus the scoping ('of a company'), so the operation is unambiguous. It doesn't distinguish itself from sibling moego_get_payment (single) or moego_list_orders, which share the same domain vocabulary, leaving an agent to infer the boundary.

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 phrase 'optionally for given orders' implies when to pass order_ids, but there is no explicit guidance on when to pick this over moego_get_payment for a known payment or over moego_list_orders. Usage is implied rather than 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?

readOnlyHint=true already declares the safe-read profile, so the description only needs to add context. It does add one useful fact — the operation is a POST-based list endpoint (/v1/pets:list) — but says nothing about pagination behavior, result size limits, or ordering, which matter for a paged list tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short, front-loaded sentences with no filler; the scope statement comes first and the endpoint is last. Slightly terse rather than padded, which is the right failure mode here.

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?

Six parameters with full schema documentation and a readOnly annotation cover the mechanics, but with no output schema the description should at least say what a pet record or the pagination envelope looks like, and it does not.

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. The description roughly maps to customer_ids and updated_after/updated_before, but it calls them "owner ids" while the schema field is customer_ids, and it omits page_size/page_token semantics entirely.

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 pets of a company") with the scoping entity named, so the agent knows exactly what is returned. However, it never distinguishes itself from the very similar sibling moego_list_customer_pets or from moego_get_pet, leaving a real risk of sibling collision.

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?

"Filter by owner ids or last update time" implies when the two filter modes are useful, but there is no explicit when-to-use guidance, no exclusion of alternatives, and no stated reason to pick this over moego_list_customer_pets.

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?

readOnlyHint=true already covers the safety profile, so the bar is lower; the description adds the concrete endpoint (POST /v1/reports:list) and clarifies that the return payload is report ids usable downstream. It does not mention pagination or result ordering, which is a real gap for a list tool, 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?

One sentence, zero filler, with the resource and the downstream consumer front-loaded. 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?

With no output schema, the description usefully characterizes the return value as report ids and points to the tool that consumes them. Minor omission around pagination/volume of results keeps it from a 5.

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 single company_id is already documented with its source (moego_list_companies). The description's 'for a company' adds no syntax or format detail beyond the schema, so the 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?

Specific verb (list) plus resource (business reports) plus scope (for a company), and it explicitly names the sibling that consumes the output, moego_fetch_report_data. An agent can distinguish it from the many other list_* siblings immediately.

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 parenthetical '(ids for moego_fetch_report_data)' establishes the intended workflow ordering: list here, then fetch data there. It stops short of stating exclusions or when-not-to-use, but the routing signal is clear and correct.

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, so the safety profile is covered. The description adds nothing beyond that — it does not mention that results are paginated, how to iterate pages, or whether filtering by business is optional. The endpoint string ('POST /v1/retail/products:list') is the only additional fact and carries little behavioral value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the purpose front-loaded. The API endpoint line is arguably redundant for an agent but is compact and does not obscure the main statement.

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 simple read-only list tool with fully documented parameters and a readOnlyHint annotation, the description is minimally sufficient. However, it never signals pagination behavior (page_size/page_token exist but the description doesn't say results are paged or that a nextPageToken is returned), which is the main thing an agent would need to know before calling.

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 four parameters (company_id, business_ids, page_size, page_token) are already documented in the schema, including cross-references to moego_list_companies and moego_list_businesses. The description adds no parameter meaning beyond that, 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 a specific verb and resource ('List retail products for sale'), which is unambiguous and distinct from the many other list_* siblings (orders, packages, discounts). It stops short of explicitly contrasting itself with adjacent catalog-like siblings such as moego_list_packages or moego_list_discounts.

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 no guidance on when to use this tool versus alternatives, nor any prerequisites beyond what the schema requires. The only extra content is the raw API endpoint, which is developer metadata rather than agent-facing usage guidance.

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