OfficeRnD MCP by usefulapi

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

Annotations only supply destructiveHint=true; the description adds the required OAuth scope (flex.collaboration.ticketComments.create), the write nature of the call, and the member/public-attribution constraint. It does not describe the response payload or whether comments can be modified afterward, but the added operational context is substantive and consistent with the annotation.

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, with no filler. The trailing 'OfficeRnD: POST /ticket-comments/{ticketId}' endpoint notation is low-value implementation detail, but the body is otherwise tight.

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 four required parameters, no output schema, and only a destructiveHint annotation, the description covers the essentials: auth scope, write semantics, visibility rules, and the attribution constraint. It leaves unclear what the call returns and whether the posted comment is mutable, a minor gap for a straightforward create 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?

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by stating the cross-parameter constraint that a comment attributed to a member must be public, which is not expressed anywhere in the schema. It does not extend the meaning of text or ticket_id 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?

Opens with a specific verb+resource pair ('Post a comment on a helpdesk ticket') and a WRITE marker, which cleanly separates it from siblings like officernd_create_ticket and officernd_list_tickets. An agent can identify the action 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?

Provides a real conditional rule ('comments attributed to members must be public') and the visibility meaning of public comments, which shapes invocation. However, it never states when to choose this tool over alternatives or when not to use it, so guidance is implied rather than explicit.

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

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

Annotations only supply destructiveHint=true, so the description carries most of the burden and does so well: it discloses billing side effects (charged per the resource's rate unless is_free/is_tentative), notification side effects (member notified unless is_silent), and the required OAuth scope flex.space.bookings.create. The 'WRITE' marker is consistent with destructiveHint=true, so there is no contradiction.

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?

Four tight sentences, front-loaded with the operation type ('WRITE') and the core action, followed by side-effect conditions, then scope and endpoint. No sentence is filler and no information is 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 13-parameter write tool with no output schema, the description supplies what an agent needs beyond the fully-documented schema: mutation semantics, cost/notification consequences, required scope, and the underlying API route. Nothing material is missing for correct invocation.

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 schema already defines all 13 parameters and the baseline would be 3. The description goes further by explaining cross-parameter interactions the schema cannot express — that is_free/is_tentative suppress charging and is_silent suppresses notification — which materially changes how an agent sets those flags.

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 ('Book a resource (e.g. a meeting room) for a member and/or company') and front-loads 'WRITE', so the agent immediately knows this is the create path rather than the sibling read tools (officernd_get_booking, officernd_list_bookings). It even names the backing endpoint (POST /bookings), making the resource 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?

The description makes clear when this tool applies (booking a resource for a member and/or company) and explains the conditional branches that govern the call (charged unless is_free/is_tentative, notified unless is_silent). It does not explicitly name alternatives such as officernd_get_booking or officernd_list_booking_occurrences, but the create-vs-read distinction is self-evident from the verb.

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

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

Annotations only declare destructiveHint=true; the description adds real value beyond that by flagging 'WRITE', naming the required scope (flex.community.members.create), and citing the underlying endpoint (POST /members). It does not describe side effects, what a partially-successful create does, or rate limits, but the auth/scope disclosure is meaningful behavioral context.

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 terse sentences, front-loaded with the 'WRITE' signal, followed by purpose, scope requirement, and endpoint. Every sentence earns its place with 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 an 11-parameter mutation with a nested object and no output schema, the description covers purpose, auth scope, and endpoint but never says what is returned (e.g., the created member's id), which an agent typically needs after a create. It is adequate but leaves that 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%, so all 11 parameters are already documented, establishing a baseline of 3. The description only adds the location/company relationship and does not explain the nested 'properties' object or the boolean billing/contact flags beyond what the schema already says.

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 ('Add a new member (person) to a location'), and clarifies the optional company attachment. It implicitly distinguishes itself from officernd_update_member and officernd_get_member via 'add a new', though it never names them, so sibling differentiation is left to inference.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. The only contextual hint is the passing 'optionally attached to a company', which implies a mode of use but does not tell the agent when to prefer this tool over update_member or how to handle the prerequisites.

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

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

Annotations only supply destructiveHint=true; the description adds beyond that by disclosing the required OAuth scope (flex.collaboration.tickets.create) and the underlying POST /tickets endpoint. It does not explain what the destructiveHint implies for a create operation (e.g. irreversibility, notifications), leaving a modest 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?

Front-loads the write marker and the one-sentence purpose, then appends dependency, scope and endpoint facts compactly. Every clause is short and useful, though the trailing 'OfficeRnD: POST /tickets' adds little for an agent that invokes by tool name.

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 7-parameter create tool with full schema coverage and no output schema, the description supplies the pieces the schema cannot: the write nature, the option-id lookup dependency, and the auth scope. Nothing critical is missing, though failure/response behavior is unaddressed.

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 schema already documents every parameter including the category semantics of type/priority/severity. The description's main addition is naming officernd_list_ticket_options as the lookup source, which is useful but largely overlaps the schema's own 'Ticket-option _id with category' text. 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 ('Open a helpdesk ticket on behalf of a member'), which is separable from sibling creators like officernd_create_booking and officernd_create_member. The leading 'WRITE.' marker reinforces the operation class 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?

Gives clear context: it names officernd_list_ticket_options as the source of the type/priority/severity option ids, which is exactly the prerequisite an agent needs. It does not state when *not* to use it or contrast against officernd_add_ticket_comment or list_tickets, so it falls short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read. The description reinforces the read-only nature and lists the fields returned, but adds no auth requirements, rate-limit behavior, or not-found handling, so it adds only modest context beyond structured data.

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 compact sentence front-loads the action and resource, then lists fields and the endpoint. Nothing is wasted or 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 simple single-record read with full schema coverage and readOnlyHint annotation, the description supplies the lookup key, the returned field set, and the underlying endpoint. Since no output schema exists, the field enumeration is useful and no critical agent need is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the sole parameter's description ('The booking _id.') already explains the input. The description's 'by _id' phrasing is consistent but adds no syntax, format, or constraint detail 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?

Specific verb 'Fetch' plus resource 'one booking' and the exact lookup key '_id'. Enumerates the returned payload (resource, member/company, times, recurrence rule, fees, extras, visitors, status) and cites the underlying GET endpoint, distinguishing it clearly from the list_* booking 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?

Makes the trigger condition clear: use when you have a single booking _id and need that record. However, it does not name alternatives such as officernd_list_bookings or officernd_list_booking_occurrences or state when not to use it, so it stops short of full when/when-not guidance.

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

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

readOnlyHint=true already tells the agent this is a safe read, and the description adds real value on top by disclosing the returned data shape (a single member with billing and custom properties) plus the underlying REST call GET /members/{memberId}. No destructive side effects or auth constraints are described, but none are plausibly needed for a pure fetch.

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, front-loaded with the action and the lookup key, followed by the payload summary. The trailing 'OfficeRnD: GET /members/{memberId}' is redundant scaffolding but cheap and mildly useful for endpoint mapping.

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

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

There is no output schema, so the description carries the burden of stating what comes back — and it does list the returned facets. Together with annotations this is sufficient to call the tool correctly; only the absence of an error/not-found behavior note keeps it from full completeness.

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 required parameter is documented as 'The member _id', so the baseline of 3 applies. The description's '_id' reference matches the schema but adds no syntax or format detail beyond it.

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 (one member) with the lookup key (_id), and enumerates the returned facets (contact details, company, location, status, billing, custom properties), which clearly separates it from the list_members sibling. It stops short of explicitly naming the alternative tool, so it is clear but not sibling-routing.

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

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

Usage is implied by the '_id' lookup key — an agent infers it applies when a concrete member ID is already known and list_members/search would be used otherwise — but no when-to-use or when-not-to-use condition is 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 covers the safety profile, so the description's marginal burden is low. It adds useful framing that the call is cheap and credential-scoped, but says nothing about failure modes (e.g. what happens with invalid credentials) or response shape beyond three field names.

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, zero waste, front-loaded with the verb+resource followed by the value proposition and the underlying API route. Every clause earns its place.

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 zero-param read with annotations covering safety and a described return payload, this is nearly complete. A brief note on auth failure behavior or whether region affects later calls would close the remaining 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?

Zero parameters, so baseline is 4. The description correctly implies the org is inferred from credentials rather than passed as an argument, which is meaningful given the API route shows a {orgSlug} path variable.

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

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

States a specific verb and resource ('Fetch the OfficeRnD organization') and enumerates the returned fields (name, slug, region), which no sibling does. An agent can distinguish this org-lookup from member/booking/ticket tools 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?

Provides one implied use case ('a cheap way to confirm the setup works') but does not name alternatives or state when not to use it. Adequate but thin for a routing decision among 19 siblings.

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 a real operational constraint (max 1-year window unless paginated) that an agent cannot derive from the schema. It stops short of describing pagination mechanics or return shape, but the added constraint is substantive.

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

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

Three compact sentences, front-loaded with the purpose, then usage, then the operational constraint and endpoint. No filler or repetition.

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, 11-parameter list tool with no output schema and full schema coverage, the description covers purpose, scope, sibling distinction and the key window constraint. Return shape and pagination loop details are absent, but the essentials for correct invocation are present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% across all 11 parameters, so the schema already documents from/to, cursors, filters and limits thoroughly. The description only implicitly touches parameters through the 1-year/pagination remark, adding little beyond the schema. 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 every individual booking occurrence') and then disambiguates the resource itself: one-off bookings plus each expanded instance of recurring series. This clearly separates it from the sibling officernd_list_bookings, which an agent would otherwise confuse it with.

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 concrete usage context ('the right tool for calendars, room availability and utilisation') and implies a pagination condition via 'without pagination the window may be at most 1 year'. However, it never explicitly names officernd_list_bookings as the alternative or states when that tool is preferred, so routing is still partly inferential.

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 read-only safety profile is covered. The description adds genuinely non-obvious behavior beyond the annotations and schema: recurring series are collapsed to their first instance, which materially changes what the caller receives. It stops short of describing pagination interaction or return ordering, so it is not exemplary.

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: the core semantics first, then the filter scope, then the alternative tool, then the endpoint. Every sentence carries distinct information and nothing is repeated from the structured fields.

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 12-parameter list tool with no output schema, the description covers the critical ambiguity (series vs. occurrence granularity) and the endpoint. Pagination and return-shape behavior are left entirely to the schema's cursor descriptions, which is acceptable but leaves the description slightly short of fully self-contained.

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%, with each of the 12 parameters documented in the schema itself (including limit bounds, cursor usage, and ISO 8601 formats). The description only restates the filter categories in prose, adding no format or syntax detail beyond the schema. 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 (list) and resource (bookings), and immediately specifies the aggregation semantics: one entry per one-off booking and one per recurring series (first instance only). It explicitly names the sibling officernd_list_booking_occurrences as the contrasting tool, so the agent can distinguish the two list endpoints 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 an explicit routing rule: use this tool for series-level listings, use officernd_list_booking_occurrences for every individual occurrence in a date window. It also enumerates the filterable dimensions (member, company, location, resource, series start window, status), which tells the agent when this tool is the right fit.

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 that this is a safe read operation, so the bar is lower. The description adds useful context about the returned data and the underlying GET endpoint, but does not cover pagination behavior, rate limits, or authentication needs beyond what the schema and annotations already provide.

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

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

The description is compact and front-loads the key resource information, with a brief endpoint note at the end. Every element is relevant, though the endpoint notation is somewhat redundant for an agent that already has the tool name.

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 list tool with full schema coverage and annotation-backed safety, the description provides enough context about what is returned and why it is useful. It does not need to explain pagination or filters because the schema covers them, though it also does not mention output format or result ordering.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all eight parameters are already documented in the schema. The description does not add any filtering, date-range, or cursor semantics beyond what the schema provides, making the baseline of 3 appropriate.

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

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

The description uses a specific verb (List) and resource (member check-ins), and clarifies the returned fields (who was on site, when, and via which booking or pass). It does not explicitly differentiate from sibling list tools like list_bookings or list_members, 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?

It gives a clear use case ('useful for occupancy and attendance'), which implies when the tool is relevant, but it does not state when to prefer it over alternatives or mention any exclusions or prerequisites. Usage guidance is therefore only implied.

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 bar is lower; the description adds only the upstream mapping (GET /companies). It does not mention pagination behavior, default/max page size, or that unfiltered calls may return large result sets, all of which matter for a 9-parameter list endpoint.

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 listed and what can be filtered, with the API reference trailing. No filler or repetition of schema details.

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 list tool with full schema coverage and no output schema, the definition covers what an agent needs to call it correctly; the resource meaning is clarified and the endpoint is mapped. It stops short of noting cursor-based paging expectations or the shape/size of the returned collection.

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 nine parameters (sort, limit, cursors, modified_since, etc.) are already documented with formats and constraints. The description echoes only four of them ('name or _id, location and status') and adds no syntax or semantics 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?

States a specific verb and resource and even disambiguates the domain term ('companies (teams/tenants renting space)'), so an agent knows exactly what is listed. It does not, however, contrast itself with the many sibling list tools (members, locations, contracts, bookings), so routing relies on the resource 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 phrase 'filterable by exact name or _id, location and status' implies the intended lookup scenarios, but no explicit when-to-use/when-not guidance or alternative tool is named. An agent can infer usage but gets no help choosing between this and, e.g., officernd_list_members or officernd_list_locations.

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 burden is light. It adds useful context on the returned payload (totals, dates, notice period, status, lifecycle stage) but says nothing about pagination behavior, result size, or ordering defaults, which matter for a 9-param cursor-paginated list.

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

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

A single front-loaded sentence: verb+resource first, definition and returned fields next, use case last, with the endpoint as a trailing tag. No filler or repetition.

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, and the description does describe what the list yields; cursor parameters for pagination are schema-documented. The gap is that paging/limit behavior is never mentioned in prose, which slightly weakens the picture for a list endpoint with 9 optional params.

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 in the schema; baseline 3 applies. The description echoes the status and lifecycle-stage dimensions but adds no format or syntax detail (e.g. how 'totals' relates to filters) 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 (List) and resource (contracts), then defines the resource in plain terms ('agreements for plans and resources') and enumerates the data each entry carries. No sibling tool covers contracts, so this is trivially distinguishable from the other 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 example 'find contracts up for renewal or serving notice' gives concrete use contexts and maps directly to the stage enum values. There is no explicit when-not guidance or named alternative, but the intent is unambiguous.

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

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

With readOnlyHint=true already declaring the safety profile, the description's main addition is the list of returned fields (address, timezone, open/public flags), which is genuinely useful. It does not add pagination behavior, rate limits, or result-size guidance beyond what the schema already carries.

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 front-loaded sentences: identity and returned fields first, then the dependency/usage note. Every clause earns its place with 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 read-only list tool with a fully documented schema and no output schema, the description covers purpose, returned content, and the key downstream dependency. Nothing essential to selecting or invoking the tool is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all six parameters are fully documented in the schema, including limit bounds and cursor semantics. The description adds no parameter-level meaning, 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?

States a specific verb (List) and resource (the organization's locations), and disambiguates the resource as coworking spaces/buildings with the fields returned. It clarifies role relative to other tools ('neoed by most other filters'), though it never contrasts itself against sibling list tools like list_resources.

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 a concrete when-to-use reason: the location _ids returned are required by most other filters and by officernd_create_member. It provides clear context but no explicit exclusions or edge cases (e.g., when a name filter is unnecessary).

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 by structured data. The description adds modest behavioral context: the exact-match semantics of the email/name filters and the underlying 'GET /members' endpoint. It says nothing about pagination behavior, ordering guarantees, or result size, which the schema only partially implies via the limit and cursor parameters.

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, no filler, with the tool's scope and its filter set front-loaded before the API endpoint note. Nothing is wasted and the key information arrives first.

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 13-parameter list tool with no output schema and only a minimal readOnly annotation, the definition covers purpose and filters but leaves the return shape (array of members, field set), pagination workflow, and default page size unaddressed in prose. The fully documented schema compensates on parameters, but an agent gets no picture of the response.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 13 parameters in detail, making 3 the baseline. The description adds a small amount of value by grouping the filters and flagging that email/name are exact matches, but it omits sort, limit, cursor, and is_billing_person entirely, adding no 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 and resource ('List members (people) of the workspace') and enumerates the filterable dimensions, which is more than a restatement of the title. It does not, however, explicitly distinguish itself from the sibling officernd_get_member (single member) or officernd_list_companies, so an agent must infer the list-vs-get split from naming 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 list of filterable fields implies when the tool is useful (bulk retrieval narrowed by email, status, company, dates), but there is no explicit when-to-use statement, no exclusions, and no routing to alternatives such as officernd_get_member for a single record. Usage is inferable 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 establishes this as a safe read. The description adds useful context about the record shape and the notion of a platform-calculated status, but says nothing about pagination behavior (despite cursor params), result volume, or rate limits, so it only modestly exceeds what the annotations provide.

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: the first front-loads purpose and payload, the second pins the underlying 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?

With no output schema, the description usefully enumerates the fields returned, which is the main thing structured data does not cover. Combined with fully documented parameters, an agent has enough to call it correctly, though sibling disambiguation remains missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every one of the 9 parameters is already documented in the schema. The description echoes a few of the returned/queried concepts (plan, price, discount, start/end dates, status) without adding format or filtering semantics, 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 (List) and resource (memberships), and even disambiguates the domain term with a parenthetical — 'recurring plans sold to members/companies' — plus the fields the record carries. It does not differentiate itself from the closest sibling, officernd_list_contracts, so an agent must still infer which list endpoint covers which concept.

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 guidance on when to use this tool versus officernd_list_contracts, officernd_list_members, or officernd_list_payments, and no stated prerequisites or exclusions. The only usage signal is the implied 'list' behavior, leaving routing decisions to the agent.

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?

Annotation already declares readOnlyHint=true, so safety is covered; the description adds real behavioral context beyond that by disclosing what each returned document carries (totals, paid/pending amounts, due dates, status) and mapping to the underlying GET /payments endpoint. It stops short of describing pagination/cursor behavior or default sort order, but the added return-shape information is genuine 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?

A tight single sentence plus an endpoint tag — the document types and filter dimensions are front-loaded and nothing is padded. Slightly dense, but every clause (types, returned fields, filters) carries information an agent can use.

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 14 optional parameters, 100% schema coverage, and no output schema, the description supplies a useful summary of the returned document fields and filterable dimensions. The main gap is pagination/ordering guidance (cursor_next/cursor_prev and default sort semantics), which the agent must infer from the schema alone.

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 14 parameters are already documented in the schema, establishing the baseline of 3. The description lists the same filter dimensions (member, company, location, document type, status, number, issue/due date) without adding syntax, formats, or semantics beyond what the schema states.

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 (billing documents), and enumerates the document types covered — invoices, credit notes, overpayments. It also names the key return fields (totals, paid/pending amounts, due dates, status), so 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 description implies usage through the filter enumeration and gives a concrete scenario ('e.g. overdue invoices'), which helps an agent know when this tool applies. However, it never states when NOT to use it or points to any alternative sibling (e.g. get_member, list_contracts, list_memberships) that might also surface billing context, leaving routing entirely to inference.

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

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

readOnlyHint=true already declares the safety profile, so the description only needs to add context. It supplies the upstream endpoint (GET /resources) and the downstream dependency, but says nothing about pagination flow beyond what the cursor parameters imply, nor result volume. Adequate but not rich given annotations carry the safety burden.

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

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

A single dense sentence front-loads the resource scope, and the downstream-dependency note is tucked at the end where it is useful. The resource-type enumeration partially duplicates the schema's type description, costing a little efficiency.

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

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

With no output schema, the description compensates by naming the returned fields (capacity, price, rate, floor, amenities). Combined with the annotations and 100% schema coverage, an agent has enough to call it correctly; only pagination semantics remain 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 description coverage is 100%, so every parameter (name, type, limit, location, cursors) is already fully documented in the schema, including the type enumeration. The description adds no parameter-level syntax or filtering nuance, 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?

Specific verb (List) plus resource (bookable/assignable resources) with concrete examples (meeting rooms, desks, hot desks, private offices) and the fields returned. It also names the downstream consumer (officernd_create_booking needs these _ids), which separates it from sibling list tools like officernd_list_locations.

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 links the tool to its purpose: resource _ids are needed by officernd_create_booking, giving the agent a clear reason to call it. It does not, however, state when NOT to use it or name an alternative (e.g., list_locations for location _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 only declare readOnlyHint=true, so the description adds real context: it discloses the shape of each returned item (_id, category, label) and the downstream dependency on officernd_create_ticket. It omits any mention of pagination behavior despite exposing cursor parameters, which keeps it short of a 5.

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

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

A single compact sentence front-loads the resource and its contents, then adds the downstream dependency and the underlying endpoint. Every clause earns its place with no padding.

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

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

For a read-only option-list tool with no output schema, the description covers what is returned, the fields on each item, and why the caller would need it. Pagination is fully documented in the schema, so nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema already documents limit (1-50, default 50) and both cursor parameters, so the description need not repeat them. It adds no syntax or format detail beyond the schema, making the baseline 3 correct.

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 helpdesk ticket options') and immediately enumerates the concrete contents (types, priorities, severities) with their fields. This clearly distinguishes it from the sibling officernd_list_tickets, which lists actual tickets rather than configuration options.

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 the selecting condition implicitly by stating the '_ids are required by officernd_create_ticket', telling the agent when this lookup is needed. It does not, however, state any when-not conditions or name alternatives for obtaining these ids by another route.

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 read-only safety profile is covered. The description adds the underlying endpoint (GET /tickets) and the returned field set, which is genuinely useful given there is no output schema, but it says nothing about ordering, default page behavior, 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?

Two compact sentences, front-loaded with the resource and scope, with the endpoint tag appended. No filler, though the field enumeration is list-like rather than tightly integrated.

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 names the returned fields and even enumerates status values (open/new/pending/resolved). Pagination is fully covered by the schema, so the only real gap is guidance on when to use this versus sibling list tools.

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 all three pagination parameters fully documented, including the 1-50 bound and cursor semantics. 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 helpdesk tickets') and clarifies the domain with a parenthetical ('member requests/issues'), plus enumerates the fields returned. It does not explicitly contrast with the nearest sibling, officernd_list_ticket_options, so differentiation is only 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 when-to-use guidance: nothing says when to prefer this over officernd_list_ticket_options or when a single-ticket fetch (via get) is more appropriate. Pagination is handled in the schema, but no usage context is offered in 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?

Annotations only carry destructiveHint=true; the description adds substantial context beyond that: it is explicitly a write, it is a partial/patch-style update rather than a full replace, `tags` is a destructive full-list replacement, and it names the required OAuth scope (flex.community.members.update) plus the underlying endpoint. That is exactly the extra disclosure annotations cannot provide.

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 with the WRITE flag front-loaded, then capability scope, then the critical partial-update caveat, then auth/endpoint metadata. No filler and nothing buried at the end that should be first.

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 9-parameter, nested-object write tool with no output schema, the description covers the operation type, partial-update semantics, destructive tag behavior, and auth scope. It stops short of stating failure modes (unknown member_id, invalid custom property) or what a successful response returns, but nothing essential to calling it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and every parameter is individually documented, so the schema already carries the load. The description's field list and the `tags` replacement note largely restate what the schema says ('Replaces the member's entire tag list.'), so it adds little on top. 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?

States a specific verb (Update) and resource (a member) and enumerates the exact mutable surface: name, email, phone, start date, billing/contact flags, tags, custom properties. Combined with the WRITE marker, an agent can distinguish this from officernd_create_member and officernd_get_member 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?

It discloses the key operational rule — 'Only the fields you pass are changed' — which tells the agent how to invoke it, and gives the required scope. But it never contrasts with siblings (e.g. create_member to add, get_member to read) nor states when an update is the wrong choice. 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.