Pobuca Connect MCP by usefulapi

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

Goes beyond the annotations by spelling out the consequence of idempotentHint=false (two calls create two contacts) rather than just repeating the flag, and by disclosing a payload constraint the schema omits entirely: at least one of firstName, lastName or email is required even though the schema lists zero required parameters. That dedup/validation context is exactly what an agent needs before a write.

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 clauses, zero filler: write nature, minimum payload, non-idempotency risk plus the mitigating sibling, and the endpoint. The most decision-relevant facts (WRITE, minimum fields, dedup warning) are 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?

For a 36-parameter mutation with no output schema this covers the essentials: it is a write, it is non-idempotent, and what the minimum viable payload is. The notable gap is the return value — the agent is not told whether the created contact (and its id) comes back, which matters for chaining into update/get calls.

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

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

With 36 parameters and only 33% schema description coverage, the description carries real weight and does supply the single most important rule (the one-of-three identity requirement) that the empty `required` array hides. Beyond that it says nothing about the many undocumented fields (teamId, organizationId, consent flags), so it only partially compensates for the coverage gap.

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

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

States a specific verb and resource ("create a new contact in the Pobuca Connect address book") and prefixes it with WRITE, so it is instantly separable from the get_/list_ siblings and from pobuca_update_contact. The endpoint (POST /api/v1/Contacts) anchors exactly what is being created.

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 pre-condition workflow: search with pobuca_list_contacts first to avoid duplicates, because the call is not idempotent. It does not explicitly contrast with pobuca_update_contact (the create-vs-update choice is only implied by the verb), but the when-to-use guidance is clear and actionable.

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=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true. The description concretizes the non-idempotency into a real-world consequence (duplicate organizations) and adds the underlying endpoint POST /api/v1/Organizations. It stops short of stating what a successful response contains or what permissions/quotas apply, so not a 5.

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

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

Three short sentences: the write classification is front-loaded, then the idempotency hazard, then the endpoint for reference. Nothing redundant beyond a brief endpoint citation.

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 23-parameter create operation with no output schema, the description covers the mutation hazard well but says nothing about the optional field surface or whether the created organization is returned with an id. Minimum viable: an agent knows how to call it safely but not what to expect back.

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 23 parameters at only 43% schema description coverage, and the description mentions none of them, not even the single required 'name' field. With schema coverage this low, the description was the place to explain the consent flags, customFields structure, and id-based references, and it does not compensate.

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 ('create a new organization (company)') plus the system it acts on. Easily distinguished from pobuca_get_organization, pobuca_update_organization, and pobuca_list_organizations, and the 'WRITE:' prefix signals 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?

Explicitly warns that the call is not idempotent and prescribes the mitigating action: search with pobuca_list_organizations first. This names the alternative tool and the condition under which it should be used, leaving nothing to inference.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description's job is to add context. It does so by enumerating the full returned payload, which matters here because there is no output schema. It stops short of noting not-found/error behavior or whether the response is a superset of nullable fields.

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

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

Two compact clauses, front-loaded with the resource and scope, with the returned fields adding real information rather than filler. The raw endpoint path is slightly extraneous 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?

For a single-parameter read tool with full annotation coverage and complete schema documentation, this is close to sufficient: it tells the agent what it gets back despite the absence of an output schema. Minor gaps remain around error/not-found behavior and whether absent fields are null or omitted.

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?

There is a single parameter with 100% schema description coverage, including length bounds and a pointer to pobuca_list_contacts as the source of the id. The description adds no additional semantics beyond 'by id', which is the expected baseline when the schema already documents the parameter fully.

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 contact by id') and enumerates exactly what comes back (phones, emails, addresses, organization, team, tags, custom fields), which separates it from the list tool. It never names a sibling tool, so the differentiation is inferred from scope rather than stated.

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

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

Retrieving one record by id implies its own use case, and the schema note 'Contact id (from pobuca_list_contacts)' hints at the workflow. However, the description itself gives no explicit when-to-use guidance or alternatives (e.g., use pobuca_list_contacts to search, this tool when the id is already known).

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/destructive=false, so the safety profile is covered; the description adds the meaningful behavioral fact that the result is scoped to the identity of the presented API key. With no output schema, naming the returned fields is real added value.

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

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

Two short, front-loaded fragments with zero filler; the returned fields and the endpoint path are the only content. The phrasing is clipped to the point of being slightly telegraphic.

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 no-argument identity read with no output schema, listing the returned fields and stating the key-scoping is essentially everything needed. Only error behavior (e.g., invalid/expired key) is left 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?

Zero parameters, so the baseline of 4 applies; the description correctly signals that no inputs are needed. Nothing further to document.

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 ('the Pobuca Connect user this API key acts as') and enumerates the identity fields returned, so an agent knows exactly what it gets. It's clearly a different resource from the contact/organization/team siblings, 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?

Usage is only implied by the zero-parameter, self-scoped nature of the call — there is no statement of when to reach for this versus pobuca_list_team_members or a contact lookup. 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.

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by enumerating the organization fields returned and naming the underlying GET 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?

The description is two compact sentences with no wasted wording. The core purpose is front-loaded before the endpoint 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 simple one-parameter read tool with annotations and no output schema, the description is largely complete: it states the retrieval scope, lists returned data, and gives the endpoint. It does not mention error behavior when the id is not found, which 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?

Schema coverage is 100%, and the organization_id parameter is already documented as the id from pobuca_list_organizations. The description adds only the phrase 'by id' and does not provide additional format or validation semantics 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?

The description states a specific retrieval operation for a single organization by id, and lists the included data such as addresses, type, industry, primary contact, tags, and custom fields. This clearly distinguishes it from the sibling list_organizations tool, which returns multiple organizations.

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 retrieval by id and the schema notes the id comes from pobuca_list_organizations, which gives useful context. However, it does not explicitly state when to use this tool versus alternatives such as pobuca_update_organization or pobuca_list_organizations.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered externally. The description adds only the raw endpoint path and no behavior beyond the name — no note on error behavior for missing ids, whether the call is rate limited, or what the team object contains.

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

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

Two short fragments, front-loaded with the purpose ahead of the endpoint detail, with no filler. It is, however, terse to the point of leaving usage and output shape unstated.

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 strong annotation coverage and a fully documented schema, the definition is nearly sufficient. The remaining gap is that no output schema exists and the description does not indicate what a team record contains.

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 team_id field already explains it comes from pobuca_list_teams. The description's 'by id' adds nothing 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: fetch a single team by id, with the underlying endpoint for confirmation. It implicitly contrasts with list_teams via 'One team', but never names the sibling that fetches many, so 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?

No guidance on when to use this versus pobuca_list_teams, pobuca_list_team_members, or other get_* siblings. The only hint is that a team_id is required, which the schema already states.

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, non-destructive, open-world access, so the safety profile is covered. The description adds real operational context beyond that: a hard page cap of 50, the cursor-style continuation contract, and the underlying GET /api/v1/Contacts endpoint. It doesn't say anything about ordering defaults or what happens when include_deleted is combined with filters.

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 what is returned, then paging, then filtering – a sensible order with short, dense sentences. Minor redundancy: the filter example and the next_skip-to-skip rule repeat what the schema already states verbatim.

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 listing the returned field categories and naming the next_skip pagination field, which is what an agent needs to iterate. It's close to complete for a read/list tool; it doesn't clarify default sort order or response envelope 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 coverage is 100%, so all five parameters are already documented in the schema with the same paging and OData examples. The description reinforces the paging contract and offers a realistic filter example, but adds no syntax or constraint detail the schema doesn't already carry; 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 contacts (people)') and enumerates the fields returned (names, phones, emails, addresses, organization, team, tags, custom fields). This clearly separates it from the singular pobuca_get_contact and from pobuca_list_organizations without needing to open 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 concrete guidance for the common retrieval scenario ('To find recently changed contacts use $filter like "updatedat ge …"') and explains how to continue paging via next_skip. It lacks explicit exclusion language (e.g. 'use pobuca_get_contact when you already have an id'), so it stops short of full 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?

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral detail beyond that: a hard cap of 50 results per call, the next_skip chaining convention, OData query support, and the underlying endpoint. Return format is not described, but for a read-only list tool that is a minor gap.

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

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

Three short sentences, front-loaded with the purpose and followed by the two constraints an agent actually needs (page cap and page chaining). No filler, no repetition of the title.

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 hint at return shape: it does so minimally ('with their codes') and it fully explains pagination, which is the main failure mode for a paged list tool. It does not describe what a next_skip token looks like or whether filtering on country fields is constrained, but nothing essential to a correct call 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 five parameters are already documented with examples, ranges and defaults. The description restates the paging and OData semantics without adding syntax, format or edge-case meaning beyond the schema, which matches the baseline for full-coverage schemas.

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 countries with their codes') and is trivially distinguishable from the sibling list tools, which cover contacts, organizations, teams, industries, etc. Nothing ambiguously overlaps another tool.

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 operational guidance (paging, page size, chaining) but never states when to use this tool versus alternatives or any prerequisites. For a simple reference-data lookup with no near-duplicate sibling, usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered structurally. The description adds genuine context by disclosing the return content (type plus dropdown options) and the underlying endpoint GET /api/v1/CustomFields/{entityType}. It stays silent on pagination behavior beyond what the skip parameter already documents.

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 its output shape, followed by a short usage note and endpoint. 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?

No output schema exists, and the description compensates by summarizing the returned fields, which is the key thing an agent needs. Minor gaps: it does not mention pagination defaults or the include_deleted/filter behavior, though those live in the schema descriptions.

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 including the entity_type enum are documented in the schema itself. The description restates the entity_type values ('contacts, organizations (\'Group\') or users') but adds no new semantics for top, skip, filter, orderby, or include_deleted; baseline 3 is 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 custom fields defined for contacts, organizations (\'Group\') or users') and even describes the payload (type Text/Dropdown plus options). The resource is distinct from every sibling list_* tool, so no disambiguation is needed beyond the entity wording.

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?

'Use the ids and option ids in the customFields of a contact or organization' tells the agent the downstream purpose — validating/selecting values before writing contacts or organizations. No explicit when-not or named alternative appears, but the sibling set contains no competing custom-field tool, so ambiguity is low.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuine behavioral context beyond that: a hard 50-per-call page cap, the next_skip→skip continuation loop, OData filter/orderby support, and 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?

Three terse clauses, front-loaded with the purpose, then pagination, then query capabilities. The trailing 'GET /api/v1/Departments' is mild filler but harmless and useful when reporting errors.

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-required-parameter read tool with no output schema, the agent mainly needs to know the page size, how to continue paging, and that filtering/ordering are supported — all present. Only the shape of an individual department record 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?

Schema description coverage is 100%, so every parameter is already documented in the schema, which sets the baseline at 3. The description restates the page size cap and the next_skip continuation pattern and mentions $filter/$orderby, but adds no syntax or semantics the schema lacks.

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 departments') and immediately clarifies what a department is here — the ids that fill a contact's departmentId. That disambiguates it well from the contact/organization/team siblings, though it does not name any 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: the parenthetical about departmentId tells an agent why it would call this (to resolve a department id for a contact), but there is no explicit when-to-use or when-not-to-use statement and no named alternative.

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=true, destructive=false and openWorld=true, so the safety profile is covered. The description adds real value by disclosing the page cap (50) and the continuation contract (pass the previous reply's next_skip as skip), plus OData support. It does not describe the shape of returned records beyond the "ids" hint.

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, each carrying distinct information: resource purpose, paging mechanics, query options and endpoint. Nothing is repeated or wasted, and the critical paging rule 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 usefully reveals that responses carry ids and a next_skip field, which an agent needs for pagination. Remaining gaps (exact record fields) are minor for a reference-data 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?

Schema coverage is 100% and each parameter is documented in the schema, so the baseline applies. The description reinforces the skip/next_skip linkage and OData filter/orderby support but adds no syntax detail beyond the schema examples.

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 industries") and clarifies the payoff: ids for an organization's industryId, which tells an agent exactly why it would call this. No sibling also lists industries, so it is unambiguous among the provided 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 parenthetical supplies the use case (resolving an organization's industryId), and the paging instructions make the call pattern explicit. It does not explicitly exclude or compare against alternatives, but no sibling competes with it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered; the description adds real behavioral value with the 50-record page cap and the exact next_skip continuation protocol. It does not mention that include_deleted pulls soft-deleted records, which is the one behavioral note still missing.

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 resource and its returned fields, then covers pagination and filtering compactly in three short sentences. The long field enumeration costs some space but does double duty as return-value documentation, which is needed since there is no output schema.

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

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

With no output schema, the description usefully enumerates returned fields and explains the paging contract end-to-end. Minor gaps remain around deleted-record semantics and nothing is said about total counts or next_skip's location in the response, 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%, so top, skip, filter, orderby and include_deleted are already documented, including the next_skip hint. The description largely restates the schema's pagination story and adds no syntax or format details beyond it, 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 the specific verb (List) and resource (organizations/companies) and enumerates the returned fields, which cleanly separates it from siblings like pobuca_list_contacts or pobuca_get_organization. The concrete endpoint (GET /api/v1/Organizations) reinforces what is being read.

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?

"Paged: 50 per call at most; pass next_skip as skip for the next page" gives actionable iteration guidance, and OData $filter/$orderby support is called out. It stops short of explicit when-to-use/when-not rules against siblings (e.g. get_organization for a single record), which keeps it below a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: a hard page cap of 50, the next_skip-to-skip continuation pattern, OData query support, and the underlying GET /api/v1/OrganizationTypes 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?

Three compact sentences: purpose first, then paging mechanics, then query capabilities and the endpoint. No filler and no repetition of the title.

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 five-parameter, read-only list tool with no output schema, the description covers the essentials an agent needs to page correctly and to know what the records are for. A brief note on what each record contains (besides the id) would close the remaining gap, though the schema already documents every parameter.

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 links the pagination loop together by naming the response field next_skip as the value for skip — a relationship not expressible in the input schema and helpful given there is no output schema. It does not add anything about filter/orderby syntax beyond what the schema examples already show.

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 organization types') and adds the practical purpose in parentheses: these ids feed the organizationTypeId field of an organization. It does not explicitly distinguish itself from lookalike reference-list siblings such as pobuca_list_industries or pobuca_list_countries, but the purpose is unambiguous.

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

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

Gives clear context for use (to obtain organizationTypeId values) and operational guidance for paging ('pass next_skip as skip for the next page'), plus the availability of $filter/$orderby. No explicit when-not-to-use or named alternative among the list_* siblings, so it stops short of a 5.

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

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

Beyond the readOnlyHint annotation, it discloses the hard page cap (50), the cursor-style paging contract via next_skip, and OData $filter/$orderby support — real behavioral facts an agent needs. It omits default ordering and what the payload items contain, 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?

Three compact sentences: purpose first, then the pagination contract, then query capabilities and endpoint. No filler; every clause carries information an agent needs.

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

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

With no output schema, the description compensates by explaining the next_skip response field needed to page. It leaves the response item shape and default sort unspecified, which is a minor gap for a read-only list 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 the baseline is 3; the description adds value by naming next_skip as the field to feed back into skip, which is not expressible in the input schema alone. It does not elaborate filter/orderby syntax beyond the schema examples.

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 users belonging to teams with their team role — which is meaningfully distinct from the sibling pobuca_list_teams that lists the teams themselves. The endpoint GET /api/v1/UserTeams reinforces the resource mapping.

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 a read-only listing use case but never states when to choose it over pobuca_list_teams or pobuca_get_team, nor any prerequisite or exclusion. Usage is inferable but not guided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description still adds real behavior beyond that: a hard page-size cap and the continuation mechanism via next_skip. It says nothing about auth requirements or what a returned team record contains, which is the remaining gap.

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

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

Three tight sentences: identity first, then paging, then query capabilities, ending with the endpoint. No filler or redundancy.

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

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

For a read-only list tool with a fully described schema and no output schema, this covers enough to invoke it correctly. The main omission is which team field names are valid for $filter/$orderby, which an agent would need for anything beyond the simplest query.

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 five parameters are already documented with examples and bounds. The description mostly repeats the schema (50 max, filter/orderby support) and only marginally adds by revealing that the response exposes a next_skip field to feed back into skip. 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?

"List teams" gives a specific verb plus resource, and the parenthetical "the groups that own and share contacts" defines what a team is versus a contact or organization. It does not explicitly distinguish itself from nearby siblings such as pobuca_get_team or pobuca_list_team_members, so it stops short of full sibling differentiation.

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

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

It supplies concrete operational guidance: max 50 per call, pass next_skip as skip for the next page, and OData $filter/$orderby are supported. There is no explicit when-not or named alternative, but the usage pattern is clear and actionable.

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 flag destructive=true and idempotent=true; the description adds the crucial detail the annotation cannot convey — that it is a partial patch ('only the fields you pass are sent') but that tags and customFields are wholesale replaced. It omits what happens if contact_id does not exist and whether a malformed custom field erases existing values, keeping it below 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?

Four short clauses, front-loaded with the 'WRITE:' marker, then semantics, then safety advice, then endpoint. No sentence is filler.

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

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

For a 37-param destructive update with no output schema the description covers the essentials: mutation type, partial-update semantics, the two replace-not-merge fields, and a verification step. Still missing error/nonexistent-id behavior and whether the updated record is returned.

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

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

With 37 parameters and only 35% schema description coverage, the description should compensate more. It does address the two highest-risk collections (tags and customFields are replaced as given) and the partial-update rule for the other 35 fields, but the remaining booleans (allowSms/allowEmails/allowPhones) and id-reference params are left to 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 ('change fields of an existing contact') and even names the HTTP method and path, so an agent can distinguish it from pobuca_create_contact. It does not explicitly contrast with the sibling updater (pobuca_update_organization), but the resource word 'contact' does that work implicitly.

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?

'Look the contact up first and confirm the right one' is concrete pre-call guidance that points at pobuca_get_contact/pobuca_list_contacts without naming them. No explicit exclusions (e.g. 'use create_contact for new contacts'), 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the description's job is to add specifics — and it does, disclosing that tags and customFields are replaced wholesale rather than merged, plus the PATCH endpoint. It omits how to clear a field or what the response looks like, so not exhaustive.

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 sentences, front-loaded with the WRITE marker and the partial-update rule, then the destructive caveat, then the lookup precondition, then the endpoint. Nothing is redundant.

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

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

The high-risk aspects (partial send, array replacement, verify-before-write) are covered, which is the important part for a 24-parameter destructive mutation. But with no output schema and half the parameters undocumented, an agent still lacks guidance on field-level semantics and on what the call returns.

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

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

Schema description coverage is only 46% across 24 parameters, so the description needs to carry meaning for the undocumented ones. It only explains the replace-on-update behavior of tags and customFields, leaving fields like fax, website, profession, and all billing/shipping address parameters entirely unexplained in both schema and description.

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

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

'WRITE: change fields of an existing organization' gives a precise verb, resource and mutation class, and 'only the fields you pass are sent' pins the partial-update semantics. Together with 'existing' it separates this from pobuca_create_organization and pobuca_update_contact without needing 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?

It states a clear precondition — look the organization up first and confirm the right one — which is exactly the guidance needed before a destructive PATCH. It does not name a sibling alternative (e.g., create_organization for a new record) or say when not to use it, 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.