Spruce Health MCP by usefulapi

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds real value beyond them by enumerating what the response contains (demographics, phones, emails, tags, custom and organization fields, integration links) and naming the underlying 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 compact fragments, front-loaded with the keying dimension and then the payload; every clause 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?

There is no output schema, so the enumeration of returned fields is exactly the compensating detail an agent needs. No pagination or mutation concerns apply to a single-object read, so nothing material is missing.

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

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

Schema description coverage is 100% and the single contact_id parameter is fully documented with an example value in the schema. The description restates the id but adds no syntax or format detail beyond what the schema already provides, 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 the specific resource (a single Spruce contact) and the retrieval key (contact id, entity_…) plus the payload composition. The singular 'one contact by id' implicitly separates it from list_contacts and search_contacts, 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?

The 'by contact id' framing implies you must already have an id, which is useful context, but there is no explicit when-to-use guidance nor a pointer to list_contacts/search_contacts for finding 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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the agent knows this is a safe, repeatable read. The description adds the id prefix convention ('t_…') and the underlying endpoint, which is modest extra context but no return-shape or error behavior.

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

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

Two short fragments, no filler, and the identity of the resource is front-loaded. It is arguably too terse for a 5, but nothing is 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?

For a one-parameter idempotent read the annotations carry the safety profile, but there is no output schema and the description says nothing about what a conversation object contains or whether related items must be fetched separately. The definition is minimally workable but leaves the return payload opaque.

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 documents conversation_id including the 't_' prefix example. The description's '(t_…)' hint duplicates the schema example rather than adding meaning, 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 ('One conversation by id') and gives the REST path, so the agent knows this fetches a single conversation rather than a list. It does not explicitly distinguish itself from siblings like get_conversation_item or list_conversations, so it falls short of a 5.

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

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

There is no guidance on when to use this versus get_conversation_item (for items within a conversation) or list_conversations. The singular phrasing implies a single-record fetch, but alternatives and conditions are left 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=true, so safety/idempotency are covered. The description adds useful context in the item-type enumeration and the 'ti_' id prefix, plus the underlying REST path, but nothing about error behavior or response 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, front-loaded fragments with no filler; the item types are packed into the first clause. The REST path is marginally redundant with the tool name but 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?

For a single-parameter, idempotent read with full annotation coverage and no output schema, the description supplies everything needed to invoke it correctly. It only lacks an explicit pointer to the listing tool that produces the 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 description coverage is 100% and the schema already supplies the parameter description and an example id, so baseline is 3. The description's 'ti_…' hint is redundant with the schema example rather than additive.

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: fetches a single conversation item by id, and enumerates what an item can be (message, note, call, voicemail). The singular 'One conversation item' implicitly distinguishes it from the list_conversation_items sibling, though that sibling is never named.

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 rather than stated: 'by id' signals this is a single-item lookup requiring a known id (presumably from list_conversation_items), but no when/when-not condition or alternative tool 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is fully covered. The description adds only the underlying REST path (GET /organization/members/{memberId}), which is mildly useful for cross-referencing but discloses nothing new about behavior, errors, or permissions.

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 resource description front-loaded and no filler. The endpoint path is arguably redundant for an agent, but it is short and never buries the point.

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, annotation-rich read tool with no output schema, the description covers the essentials and usefully disambiguates that 'member' spans teammates, teams, and the organization itself. Slightly more guidance on obtaining a member_id would make it 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% and the single member_id parameter already documents format, length bounds and an example value. The description adds no syntax or constraint detail beyond the schema, 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 resource and retrieval mode: 'One organization member ... by id', and parenthetically clarifies what a 'member' can be (teammate, team, or the organization). This distinguishes it from the list_* siblings well enough, though it never names them 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 'by id' phrasing implies the single-item lookup scenario, but there is no explicit when-to-use guidance or mention of alternatives such as sprucehealth_list_members or sprucehealth_list_team_members when the id is unknown. 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds modest context — that the returned id is the owner/member id reused by other objects, and the endpoint path — but says nothing about auth requirements or error behavior. With annotations carrying the safety burden, a 3 is appropriate.

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 short fragments, front-loaded with the resource and its most useful field semantics. The trailing 'GET /organization' is largely redundant given the tool name, which is the only real waste.

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 parameters, the description correctly shoulders the job of describing the return shape, and it does so at a high level (id and name). It is adequate for a trivial, well-annotated singleton lookup; only the exact response envelope is left unspecified.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There is no parameter information the description could add or omit.

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

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

The description names the resource (the Spruce organization) and its returned fields (id and name), and distinguishes it from sibling list/get tools by noting the id is the owner/member id referenced by other objects. It stops short of an explicit verb in the body (the title 'Get the organization' carries that), but the intent 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?

'Good first call' gives explicit sequencing context, telling the agent when to reach for this in a workflow. However, no alternatives or exclusions are named, and nothing clarifies what this tool should not be used for versus siblings like get_member or list_members.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds only the REST path and id prefix, which is modest extra context, not deeper behavioral disclosure.

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

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

Two short fragments, front-loaded with the resource and the identifier requirement, with zero filler. Every element 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 single-parameter read tool with no output schema and full annotation coverage, the definition gives enough to call it correctly. Only the missing explicit alternative (list_phone_lines) keeps it from being 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?

The single parameter is fully documented in the schema (100% coverage) including the pd_ example, so the description adds nothing beyond it. Baseline 3 applies when the schema carries the 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?

The description states a specific verb and resource (retrieve one phone line by id) and includes the id prefix format. It implicitly contrasts with the sibling list_phone_lines by specifying a single record, though 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: 'by id' tells the agent it needs an identifier, but there is no explicit when-to-use versus list_phone_lines, and no exclusions or prerequisites stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: the status lifecycle (pending/completed/failed/noSpeech), which tells the agent the transcription may not be ready yet. It does not describe auth or rate-limit traits, so it stops 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?

Front-loaded with the return payload, then the id source, then status values and the endpoint — three short fragments with no filler. Slightly dense and telegraphic, but every element 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?

There is no output schema, so the description must carry the return contract, which it does by naming the transcription text, the optional summary, and the possible statuses. That covers the essentials for a single-read tool; explicit guidance on retrieving the id first would push it higher.

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

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

Schema description coverage is 100% and the single parameter is already documented in the schema as coming from a conversation item's audio attachment. The description's parenthetical ('the transcriptionId on a call/voicemail attachment') largely restates that, adding a marginal call/voicemail detail. Baseline 3 applies when the schema carries the parameter definition.

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 (retrieve a transcription) and immediately names what is returned: the full transcription text and its summary. The mention of transcriptionId on a call/voicemail attachment and the REST path make the resource unmistakably distinct from siblings like get_conversation_item or get_phone_line.

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 hints at origin by noting the id comes from a call/voicemail attachment, which implies usage after inspecting a conversation item, but it never explicitly says when to call this vs. alternatives or states prerequisites. Usage is left largely to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds that returned conversations span multiple channels (secure, SMS/phone, email, fax), but says nothing about pagination, result limits, or auth scope. Modest added value over the annotations.

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

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

Very short and front-loaded: the substantive claim about scope and content comes first, then the endpoint reference. The bare endpoint path adds little for an agent but costs almost nothing.

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 conveying what comes back; it gestures at this via the channel enumeration but omits pagination behavior, result size, and ordering. It is adequate for a simple single-parameter read but leaves real gaps about the return payload.

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%, with the schema itself supplying the format example (entity_0E5QDGJC03000). The description adds no syntax, format, or lookup guidance beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

States the resource (conversations) and the scoping constraint (associated with one contact), backed by the GET /contacts/{contactId}/conversations endpoint. The parenthetical enumerating conversation channel types (secure, SMS/phone, email, fax) reinforces what is returned. It does not explicitly name how it differs from sibling list_conversations (all conversations), 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?

There is no explicit when-to-use statement, no exclusions, and no alternative named. The phrase 'associated with one contact' only weakly implies that you call this when you already have a contact id and want its conversations, rather than routing between this and list_conversations.

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 the full safety profile (readOnly, idempotent, non-destructive, open-world). The description adds genuinely new context: pagination behavior and that totalCount is returned. However, it says nothing about cursoring beyond what the schema already covers.

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 fragments with the resource scope front-loaded and no filler. The trailing 'GET /contacts/fields.' is weakly useful for agents that reason about REST paths but is borderline noise.

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 full schema coverage and annotations carrying the safety profile, the description covers what is needed: what is listed, that it is paged, and that totalCount comes back. No output schema exists, and the description could go slightly further on the returned shape.

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 are richly documented in the schema itself (page_size bounds and cursor semantics). The description adds no parameter-level detail, so the baseline of 3 applies.

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

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

States the specific resource ('organization-wide contact fields shown on every contact'), which distinguishes it from siblings like list_contacts and list_contact_tags. The phrasing is a noun phrase rather than a verb, but the title supplies 'List' and the scope 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 guidance on when to call this versus list_contacts, list_contact_tags, or any other sibling. The agent must infer that this returns the field *definitions* rather than field values on a specific contact.

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, idempotentHint, openWorldHint and non-destructive, so safety is covered. The description adds value beyond that by enumerating the link source systems (Elation, Hint, athena, custom) and the returned fields (type, external id, url), which partially substitutes for the absent output 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 compact fragments with the resource and returned fields front-loaded, then the endpoint. No filler, though the telegraphic colon-list style is slightly terse where a phrase would read more clearly.

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-only list tool with full schema coverage and clear annotations, the description covers the resource, source systems, return fields, and endpoint. It is essentially complete, missing only pagination/ordering behavior, which is minor.

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

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

Schema description coverage is 100% and the single contact_id parameter is fully documented in the schema, including an example value. The description restates contactId only via the endpoint template and adds no new semantic detail, 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 resource (links between a contact and external systems) with concrete examples of those systems and the fields returned. The resource is clearly distinct from siblings like list_contact_tags and list_contact_fields, though it doesn't explicitly name any alternative.

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 says what the data is but gives no when-to-use guidance, no prerequisites (e.g. valid contact id required), and no comparison to sibling list tools such as list_contact_fields or list_contact_tags. Usage must be inferred from the 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?

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: cursor paging (hasMore/paginationToken) and totalCount inclusion, which tells the agent how to iterate results. It stops short of describing rate limits, sort order, or truncation behavior.

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

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

Front-loaded with the resource and its contents, then pagination, then the alternative tool. Sentences are dense and every clause carries information; the trailing 'GET /contacts' is a minor but harmless endpoint anchor.

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 compensates by enumerating the returned fields (name, dob, phones, emails, tags, custom fields, integration links) and the paging envelope (hasMore/paginationToken, totalCount). An agent has enough to call and iterate correctly.

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

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

Schema coverage is 100% and both parameters are well documented in the schema itself, including the page_size truncation caveat. The description mentions paging but adds no syntax or format detail beyond what the schema already provides, 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+resource (list contacts) and disambiguates the scope by naming the three contact categories (patients, professionals, clinics) plus the fields returned. It explicitly distinguishes itself from the sibling search tool, so an agent can route without opening a schema.

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

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

Names the alternative (sprucehealth_search_contacts) with the condition that selects it ('to find someone'), implying this tool is for browsing/enumerating the whole organization. Clear routing context, though it does not state a hard exclusion or the direct 'use this when...' framing.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds paging behavior (hasMore/paginationToken) and totalCount, which is genuine extra context, but much of it duplicates the pagination_token schema description and nothing is said about rate limits 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 clauses, front-loaded with the resource and scope, then return/paging shape, then the endpoint. There is essentially no filler; every clause 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 no output schema, the description usefully discloses the response shape (hasMore/paginationToken plus totalCount) and the pagination loop, which is exactly what an agent needs to iterate pages. It stops short of describing whether the listing can be scoped or filtered, a small gap for a collection endpoint.

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 are documented in the schema, so baseline is 3. The description only echoes paginationToken semantics and says nothing about page_size or sensible page sizing, 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 resource (all contact tags of the organization) and its collection-level scope, so it is clearly distinguishable from sibling list tools such as list_conversation_tags or list_contact_fields. It never names an alternative explicitly, but the resource noun in the tool name plus description 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 when-to-use or when-not-to-use guidance is given. With 22 siblings, including search_contacts and get_contact, the description never says whether this is the right entry point for retrieving tag data or how it relates to tag data embedded in contact records.

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 readOnly/idempotent/non-destructive, so the bar is lower, and the description meaningfully adds that results are paged via hasMore/paginationToken, that totalCount is best-effort, and that attachment URLs are short-lived. These are genuine operational caveats beyond what annotations provide; it stops short of rate-limit or auth detail.

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 first sentence front-loads the core purpose, and the remaining clauses are dense but each carries payload (ordering, filter, paging, count caveat). No filler, though the trailing raw endpoint adds little value to an agent.

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

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

For a read-only list tool with no output schema, the description covers what is returned, ordering, filtering, and pagination thoroughly. Missing only explicit routing guidance relative to sibling list tools, 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 description coverage is 100%, so the schema already documents every parameter. The description largely restates schema content (start_from = items after that time, newest_first default) and adds little new syntax or format detail, 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 resource and enumerates exactly what 'items' means (messages, internal notes, calls, voicemails, faxes, attachments), which is more informative than a generic 'list' verb. It reads as a plural list operation distinguishable from the singular get_conversation_item sibling, though it never names or contrasts with siblings 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 implied through the ordering and start_from filters rather than stated as when-to-use guidance. There is no indication of when to prefer this over get_conversation_item, list_conversation_scheduled_messages, or list_conversation_tags, so the agent must infer routing from 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds two non-obvious traits the annotations do not: eventual consistency and the paged/one-cursor-at-a-time constraint. It does not disclose rate limits or the response envelope 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?

A single dense paragraph with the resource and returned fields front-loaded, then ordering, then paging constraints, then the endpoint. Every clause carries information, though the nested parentheses make it slightly harder to scan than it could be.

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

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

With no output schema, the description compensates by enumerating the fields present on each conversation (title, type, tags, archived, assignee, participants, last message time) and by explaining the paging cursor behavior. Nothing needed to call it correctly appears to be 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%, so the baseline is 3, but the description goes beyond it by clarifying that start_from bounds the *ordering* time rather than creation time and that it and pagination_token are mutually exclusive. That is real semantics the schema fields do not convey.

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

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

States a specific verb and resource (list the organization's conversations) and immediately enumerates the returned fields and the ordering options, making it distinguishable from narrow siblings such as sprucehealth_list_contact_conversations. An agent can tell what it gets 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?

Gives a concrete use case for start_from ('what changed since…') and an explicit mutual-exclusion rule for start_from vs pagination_token, which is genuine when-to-use guidance. It does not, however, name a sibling alternative (e.g. list_contact_conversations) for the scoped case, so it stops 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered by structured data. The description adds a modest clarification ('nothing is sent or cancelled') that reinforces the read-only framing and reassures the agent that scheduled sends are unaffected, which is useful but largely overlaps 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?

Two sentences, front-loaded with the resource and scope, with the read-only caveat immediately following and the endpoint as trailing context. Every element earns its place and there is 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 single-parameter, read-only list tool with no output schema, the description covers what the tool does, its scope, and its non-mutating nature. It stops short of hinting at the shape of returned scheduled-message objects, which is the only remaining information an agent might want.

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

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

Schema description coverage is 100% and the single conversation_id parameter is fully documented in the schema, so the baseline of 3 applies. The description adds no format or syntax detail beyond what the schema already 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?

The description states a specific verb and resource ('Messages scheduled to be sent later in one conversation') plus a scope qualifier, so the agent knows this is the conversation-scoped listing. It implicitly distinguishes itself from the org-level sprucehealth_list_scheduled_messages sibling via 'in one conversation', but never names that sibling, so the differentiation is inferred rather than explicit.

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: this returns scheduled (future) messages for a given conversation. There is no explicit when-to-use guidance, no mention of the alternative sprucehealth_list_scheduled_messages, and no stated prerequisites. Adequate but with clear gaps.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description usefully adds that results are paged and that totalCount is included, plus the underlying endpoint, but says nothing about auth needs 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?

Three compact clauses with the resource stated first, then pagination behavior, then the endpoint. No filler, though the telegraphic fragments could be marginally smoother.

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, zero-required-parameter read tool, the description plus annotations and a fully documented schema cover what an agent needs to call it. The mention of totalCount compensates for the absent output schema; only auth/permission context 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 both page_size and pagination_token are fully documented in the schema, including the cursor semantics. The description adds nothing beyond the schema for parameters, which is the expected baseline when the schema does the heavy lifting.

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

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

Names a specific verb (list) and resource (conversation tags) and states the scope as 'of the organization', which helps separate it from the similarly named sprucehealth_list_contact_tags sibling. It stops short of explicitly naming that sibling or clarifying whether these are tag definitions or tags applied to conversations.

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, no exclusions, and no reference to alternatives such as list_contact_tags or get_conversation. The agent must infer from the resource name alone when this tool is appropriate.

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, idempotentHint, openWorldHint, and destructiveHint=false, so safety and idempotency are covered. The description adds scope ('the organization's own') and the returned fields (owner and members), but discloses nothing about pagination, rate limits, or auth needs. Against a lower annotation-supported bar, this is adequate but thin.

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, tight sentence front-loads what the tool returns, followed by the raw API path. The 'GET /internalendpoints.' fragment is mildly redundant with the tool name but harmless. No wasted prose.

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 parameters, the description carries the burden of explaining what comes back. It does enumerate the endpoint types and mentions owner and members, which is a reasonable start. But it omits return shape details (fields per endpoint, pagination) and any usage context, leaving gaps for an agent to call it confidently.

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

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

The tool takes zero parameters, so there are no arguments to document and the schema is empty. Baseline 4 applies; the description adds nothing semantic beyond confirming there is no filtering, which is acceptable for a parameterless list operation.

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

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

The description names the specific resource (the organization's own channels) and enumerates what it contains: phone/fax numbers, email addresses, and Spruce Links. This clearly conveys what the tool returns. However, it does not differentiate from the sibling sprucehealth_list_phone_lines, which the enumerated 'phone and fax numbers' overlaps 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?

There is no explicit when-to-use guidance, no prerequisites, and no named alternative. The only implied usage is that it lists the organization's own endpoints. An agent must infer the context and cannot tell from the text when to prefer this over list_phone_lines or list_contacts.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: it discloses the paging contract (hasMore/paginationToken) and that totalCount is included, which matters because no output schema exists.

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 filler, with the scope statement front-loaded before the pagination and endpoint details. Every clause (fields, paging, totalCount, HTTP path) carries information.

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 steps up to describe the returned content (name, email, admin, suspended, teams, organization) and the pagination envelope, which is what an agent needs to consume the response. It is slightly thin on how teammates, teams and the organization are structured relative to one another, but nothing essential 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 both parameters (page_size, pagination_token) are already fully documented in the schema, including the cursor semantics. The description's mention of hasMore/paginationToken reinforces the schema but adds no new syntax or constraint beyond it, 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 ('All members of the organization') and enumerates the entity types returned (teammates, teams, the organization itself) plus key fields. It partially distinguishes itself from the sibling list_team_members by including the organization itself, but never names that sibling or draws the boundary 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 scope statement ('all members of the organization') hints the tool is the broad option versus team-scoped alternatives, but there is no explicit when-to-use, when-not-to-use, or named alternative. An agent must infer the relationship to sprucehealth_list_team_members and sprucehealth_get_member.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered by structured data. The description adds return-field information (id, name) and the existence of totalCount, but says nothing about pagination, ordering, or the connector context that totalCount hints at.

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

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

Front-loaded and very short: the result set and its fields lead, with the trailing 'GET /phonelines' as minor HTTP trivia that adds little for an agent but costs only a few tokens.

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 input parameters and a fully covered safety profile, the description supplies the one thing the structured data lacks: what the response contains (id, name, totalCount). Absent an output schema, it does not explain pagination behavior or response size, which is the only real remaining gap for a list endpoint.

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

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

The tool takes zero parameters, so the schema needs no elaboration and the baseline of 4 applies. The description correctly avoids inventing filters and simply characterizes the unfiltered result set.

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 ('All phone lines of the organization'), scoped to the org, and names the returned fields (id, name). The plural/all phrasing implicitly distinguishes it from the singular sibling get_phone_line, but it never names that sibling or any other to differentiate 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: 'All phone lines' tells the agent this is the unfiltered enumeration, versus the singular get_phone_line. There is no explicit when-to-use statement, no mention of prerequisites, and no named alternative to route between.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered structurally. The description adds a genuine behavioral detail the annotations do not — results are ordered oldest-first by first-read time — but says nothing about pagination, result limits, or empty-result behavior for a 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?

One compact sentence front-loads the returned information, with the raw HTTP path appended as a secondary detail. Nothing is wasted, though the endpoint string is arguably redundant for an MCP agent and slightly dilutes the otherwise tight phrasing.

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 must describe return values; it partially does so (reader identity plus first-read timestamp, ordered oldest first). It omits pagination/limit behavior and the shape of each receipt entry, leaving real gaps for a list endpoint, though the single well-documented parameter and rich annotations keep the tool usable.

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

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

Schema description coverage is 100% and the single parameter includes a concrete example value ('ti_0D4QABCC06000'), so the schema fully carries parameter meaning. The description adds no additional parameter semantics, which is acceptable here but earns only the baseline.

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

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

The description states the specific resource (read receipts for one conversation item) and the exact payload semantics ('who has read ... and when they first read it'), which cleanly separates it from siblings like get_conversation_item or list_conversation_items. The verb 'list' is only carried by the name/title, not the description body, but the resource and scope are unambiguous.

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

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

Usage is implied: an agent can infer you call this when you need read status for a single item. However, there is no explicit when-to-use statement, no prerequisite (e.g. needing a conversation item id obtained elsewhere), and no mention of alternatives such as get_conversation_item which returns the item itself.

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, idempotentHint, non-destructive and open-world, so the safety profile is covered. The description adds meaningful scope context — that templates span both private and organization-wide — plus pagination behavior, but says nothing about ordering, auth, 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 short lines, front-loaded with the resource and its scope, ending with the endpoint. Every clause carries information; it is compact without being cryptic, though the telegraphic style borders on under-explanation.

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 returned fields and the paging contract, which an agent needs to consume results. With only two optional query params and full read-only annotations, the remaining gaps (ordering, filtering) are minor.

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 itself documents page_size limits and the pagination_token cursor thoroughly. The description's mention of paging with hasMore/paginationToken mirrors rather than extends that documentation, 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 states the resource precisely — saved message templates, private and organization-wide — and enumerates the returned fields (title, text, internal/shared flags). It is clear about what the tool returns, though it offers no explicit differentiation from siblings beyond the resource 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?

There is no statement of when to use this tool versus alternatives, nor any prerequisites or exclusions. The only procedural guidance is internal paging mechanics (hasMore/paginationToken), which is about how to iterate results rather than when to select this tool.

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 readOnly, idempotent, non-destructive, and openWorld, so the safety profile is covered. The description adds genuinely useful context beyond that: pagination via hasMore/paginationToken and the presence of totalCount, which matters given there is no output 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 tight sentences plus an endpoint reference; scope is front-loaded and every clause carries information (scope, read-only, pagination envelope, route). 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?

With no output schema, the description correctly supplies the return envelope (hasMore/paginationToken/totalCount) that an agent would otherwise lack. The only gap is the absence of routing guidance against the conversation-scoped sibling.

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 documents pagination_token fully. The description restates the paginationToken concept but adds no syntax or format detail beyond the schema, making the baseline 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?

States a clear verb (list) and resource (scheduled messages) and narrows scope to 'from the organization'. This implicitly distinguishes it from the conversation-scoped sibling, but it never names that sibling to make the distinction explicit.

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 word 'organization'. No explicit statement of when to use this versus sprucehealth_list_conversation_scheduled_messages, which is the obvious alternative for a narrower scope. An agent must infer the routing.

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, idempotentHint, destructiveHint=false and openWorldHint, covering the safety profile. The description only adds that results are paged and echoes the HTTP verb, without describing rate limits, auth requirements, or what a member 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?

Three short fragments carry the resource, the id source, the pagination behavior, and the endpoint — nothing wasted and the resource scoping is front-loaded.

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 should at least sketch the shape of a returned member or how the cursor/hasMore contract works; 'Paged.' is the only hint. Combined with annotations that cover safety, the definition is adequate but leaves return-value expectations to 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 description coverage is 100%: team_id format, page_size bounds and the page-cutting caveat, and the pagination_token origin are all documented in the schema. The description adds no additional parameter meaning, 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 ('The members of one team') and pins it to the exact endpoint GET /teams/{teamId}/members, so the agent can distinguish it from the broader sprucehealth_list_members. The sibling differentiation is only implicit (via the parenthetical about where team ids come from) rather than an explicit contrast.

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 supplies a prerequisite — team ids come from sprucehealth_list_members filtered by type 'team' — which is genuine usage guidance. However, it never states when to prefer this tool over sprucehealth_list_members or sprucehealth_get_member; the agent must infer the single-team scope.

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, idempotentHint, non-destructive and openWorld, so safety is covered. The description adds genuinely useful context beyond that: it clarifies that despite being a POST endpoint it is a pure read ('changes nothing'), and it documents paging plus totalCount/totalCountRelation semantics, which annotations cannot express.

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, zero filler. Search scope and filter semantics are front-loaded, and the read-only reassurance about the POST verb is placed last where it resolves the only surprising detail.

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 but all-optional search tool with no output schema, the description covers the essentials an agent needs: filter combination rules, tag matching modes, paging, and the count semantics. It does not describe the shape of returned contact records, but with no output schema that gap is minor given the sibling get_contact 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 100%, so field-level meaning is already documented. The description still adds cross-parameter semantics the schema cannot convey: filters combine with AND, values inside one filter match ANY, tags support all/none, and totalCountRelation distinguishes eq (exact) from gte (lower bound). That is real added value above the 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 ('Find contacts by free text and/or filters') and enumerates the filterable fields, so the agent knows this is a filtered search rather than a plain enumeration. It does not explicitly name the sibling it differs from (e.g. sprucehealth_list_contacts or sprucehealth_get_contact), 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?

The description explains how filters behave (AND across filters, ANY within a filter) and that results are paged, which implies the tool's role. However, it never states when to prefer this over sprucehealth_list_contacts or when a direct get_contact lookup is the better path, and no prerequisites or exclusions are given.

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