AgencyBloc MCP by usefulapi

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

Adds substantial context the annotations cannot convey: unknown dropdown values are silently created in the account's settings, nothing is sent to the customer, activities cannot be edited or deleted through the API (a hard irreversibility constraint), and the new activityID is returned. This is exactly the kind of side-effect and lifecycle disclosure a write tool needs, and it is consistent with readOnlyHint=false and destructiveHint=false.

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 'WRITE:' and then five tight clauses, each carrying a distinct fact (entity types, dropdown semantics, follow-up rule, no customer notification, no edit/delete, return value). Zero 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 15-parameter, 8-required write tool with no output schema, the description covers the mutation semantics, the follow-up conditional, the dropdown-value coupling to account config, irreversibility, and the returned ID. An agent has everything needed to call it correctly without opening other tools.

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

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

Schema coverage is 80% so the baseline is 3, but the description adds genuine meaning: status/type/method/priority must be the exact text of the account's configured dropdowns (found under My Agency Settings > Data Administration), and the follow-up fields are conditional on status. The follow_up_all_day and related_policy_id parameters 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?

A specific verb plus resource ('log an activity') with concrete examples (call, task, renewal reminder) and the full set of attachable entity types, so an agent immediately knows what this creates. It does not explicitly distinguish itself from the sibling agencybloc_create_note, which is the main adjacent alternative, 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?

Gives real conditional guidance: when status is not Complete the activity becomes a follow-up and follow_up_user_id/follow_up_date (plus start/end times) must be supplied, with AgencyBloc doing the assignment. What is missing is an explicit routing statement versus create_note or versus editing an existing activity.

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 (readOnly=false, destructive=false, idempotent=false, openWorld=true); the description adds genuinely new behavior: no duplicate detection and that the new groupID is returned, plus the underlying endpoint. It does not mention permission/scope requirements, which is the main 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?

Four short clauses, front-loaded with the WRITE marker and the core action, then the duplicate caveat, the return value, and the endpoint. Every element adds signal with no padding.

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

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

It covers what the tool does, the duplicate risk, and the return value, but for an 18-parameter mutation tool with thin schema coverage and no output schema, an agent still lacks guidance on which fields matter or how the address and custom-field blocks behave.

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 18 parameters and only 39% schema description coverage, the description carries a heavy compensation burden but says nothing about any parameter — not the required group_name, nor the mutually-implied address_type/street/city/state grouping, nor account_manager's id-or-name convention. This is a substantial 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 group / employer business account in AgencyBloc'), disambiguates the domain term 'group', and implicitly distinguishes itself from read-side siblings by pointing at search. An agent knows exactly what object 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?

'It does not check for duplicates: search first' gives explicit pre-call guidance that routes the agent to agencybloc_search_groups. It lacks explicit when-not-to-use conditions or alternatives for attaching groups to policies, but the primary usage rule is stated.

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

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

Annotations already declare write/non-idempotent/non-destructive. The description adds genuinely non-structured behavior: no duplicate detection is performed, and the call returns the new individualID. It does not discuss permissions, error modes, or what happens on partial/invalid payloads.

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 endpoint, and each sentence carries distinct information (purpose, required fields, duplicate caveat, return value). 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?

Return shape is covered in lieu of an output schema and the duplicate caveat is included, but for a 22-parameter mutation with nested custom_fields the description leaves most field-level semantics and any auth/permission context 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?

With 22 parameters and only 36% schema description coverage, the description must compensate and largely does not — it only notes that first_name/last_name are required and all else optional. Undocumented fields (zip, city, email, gender, lead_source, servicing_agent_id, phones) get no format or semantic hints from either source.

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 individual') plus scope ('client or contact') and the backing endpoint (POST individuals/create). This distinguishes it cleanly from siblings like create_group, create_policy, and update_individual.

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 does not check for duplicates: search first' explicitly routes the agent to the search tool before creation, which is a real usage rule rather than a restatement. It stops short of naming agencybloc_search_individuals or describing when an update should be preferred over a create.

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 destructiveHint and non-idempotent, and the description layers on information annotations cannot express: the write is permanent with no edit/delete path, pinning silently unpins the previously pinned note (an important side effect on other records), and it returns the new note id. The underlying endpoint is even disclosed.

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?

Five short sentences, front-loaded with the operation class and subject, each one carrying distinct information (scope, permanence, side effect, return value). Zero 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 mutation tool with no output schema, the description supplies the return value, the permanence constraint, and the pinning side effect, which is most of what an agent needs. Minor residual gaps are the pinned default and content length limits, both of which are recoverable from the schema.

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

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

Schema coverage is only 40%, so the description carries real weight, and it does clarify that subject and body are the note content and enumerates the entity types matching the entity_type enum. But it adds nothing about the pinned flag semantics beyond the schema, and the subject/body length bounds are left entirely 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?

Names a specific verb and resource ('add one note') plus the exact hosting entity types (agent, group, individual, policy), and the cardinality constraint 'one note' separates it from bulk or list operations. An agent can distinguish it from agencybloc_list_notes 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?

The 'WRITE:' prefix and the audit-rule statement that notes can never be edited or deleted tell the caller this is the only way to record note content, which is strong usage context. It doesn't explicitly route to a sibling (e.g. list_notes to verify), so it stops short of full when/when-not guidance.

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

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

Goes well beyond the annotations by disclosing a non-obvious side effect: unknown coverage types and statuses are auto-created in the account, which matters for a non-idempotent write. It also states the return value (new policyID) and the underlying endpoint, filling gaps the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) leave open.

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?

Single dense paragraph: operation class, purpose, prerequisites, required fields, side effect, return value, endpoint — in that order, front-loaded, with no filler sentences.

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 16-param write with no output schema, the description covers what the schema cannot: the auto-creation side effect, the returned policyID, and the required-vs-optional split. The remaining parameter detail is documented at the property level in the schema.

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

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

With 16 params and 69% schema coverage, the description usefully enumerates the five required inputs and clarifies that entity_id/entity_type identify the holder and that carrier must be the full name. It adds real meaning for coverage_type/status (unknown values are created) but says nothing about the optional fields (premium, dates, custom_fields, servicing_agent_id), leaving those 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 ("create a policy") plus the key scoping constraint that it attaches to an existing group or individual, which cleanly separates it from agencybloc_create_group / agencybloc_create_individual. The "WRITE:" prefix immediately signals the operation class against the many read siblings.

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

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

"on an existing group or individual" is a real precondition that tells the agent the holder must already exist (create/search the entity first). It does not explicitly route away from agencybloc_update_policy or mention that carrier lookup may require agencybloc_search_carriers, so no explicit alternatives are 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=true and destructiveHint=false, so safety is covered. The description adds that the underlying call is a POST to activity/list (a read masquerading as a POST, worth knowing) and that the batch is capped at 50, but says nothing about what happens with unknown ids or what comes back.

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

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

Two terse clauses with zero filler; the resource and the batch bound are front-loaded. The trailing 'POST activity/list' is jargon but informative to an API-aware 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?

There is no output schema, so the description should indicate the return shape (activity records, ordering, behavior for missing ids) and does not. It is adequate to invoke correctly but leaves the agent guessing about the response.

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

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

Schema description coverage is 0%, but the single parameter is a plain integer array whose constraints (minItems 1, maxItems 50) are already encoded in the schema. The description's only added semantics is where ids originate (policy or individual records), which is useful but thin.

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 and the retrieval key precisely: activities fetched by id, in batches of 1-50. The 'by id' phrasing implicitly separates it from the sibling list_activities, though no verb ('get/retrieve') is used 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 clause 'e.g. the ids shown on a policy or individual' tells the agent where valid ids come from, which is genuinely useful context. However, it never says when to pick this over agencybloc_list_activities or agencybloc_search_* alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds the return shape and notes the underlying call is POST agents/detail — valuable because a mutating-looking verb backs a read-only operation. It does not say what happens when the id is unknown.

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 clause with the return payload front-loaded and the conditional flag parenthesized at the end; nothing is wasted. It borders on terse for a tool with a nested response, 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?

With no output schema, the description carries the burden of describing the response, and it does list the main sections returned. Gaps remain around error behavior for a bad id and whether agencies/addresses are always present, but for a two-parameter read tool it is largely sufficient.

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

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

Schema coverage is 50%: include_activities is already documented in-schema, and agent_id has no schema description. The description's mention that activities appear only when include_activities is true largely restates the schema, adding little on format or validity for agent_id.

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

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

States a specific verb and resource — fetch a single agent by id — and enumerates the payload (agencies, addresses, custom fields, optional activities). That distinguishes it in spirit from the search_* siblings, though it never names agencybloc_search_agents as the 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?

Usage is only implied: 'by id' signals you must already have an agent id, which steers away from the search tools. There is no explicit when-to-use/when-not statement and no mention of what to do when only a name or email is 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 readOnlyHint, openWorldHint and destructiveHint=false, so safety is covered; the description adds genuinely new behavior detail by declaring exactly which related collections come back and that activities are conditional on include_activities. It does not mention pagination or response shape, but for a single-record read the remaining gap is small.

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

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

A single front-loaded sentence carries the returned fields and the conditional flag; nothing is redundant. The trailing "POST groups/detail" is a transport/endpoint detail that earns only marginal place but does hint that a body is used for the detail call.

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 explaining what is returned, and it does so by naming the related collections and the flag that widens the payload. Combined with annotations covering the read-only profile, an agent has enough to call this correctly.

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

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

Schema description coverage is 50%: include_activities is already documented in the schema, and the description's restatement adds no syntax or default info beyond it. group_id has no schema description, and the description only implies "id" without clarifying the group identifier type or source; with half the parameters documented, 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?

"One group by id" states a specific verb+resource and scope, and the enumeration of included sub-resources (addresses, policies, custom fields) makes the payload concrete. It implicitly contrasts with the sibling search_groups (single record by id vs. search), but never names that alternative explicitly.

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

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

Usage is only implied: fetch-by-id is a standard pattern, and the include_activities flag hints at a lighter-vs-heavier call. There is no explicit statement of when to prefer this over agencybloc_search_groups or agencybloc_list_activities, and no prerequisites or error case (e.g., unknown id) are noted.

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, so the description is not burdened with safety disclosure. It still adds genuine context beyond them: which collections come back, that national ids are stripped (a data-redaction behavior the agent cannot infer), that activities are opt-in, and the surprising underlying endpoint 'POST individuals/detail' — a POST that is actually a read, which usefully resolves the apparent clash with readOnlyHint.

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 primary resource and its scope, then the optional expansion, then the data-handling caveat. No filler; the endpoint notation is compact and informative.

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

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

With no output schema, the description carries the return-shape burden, and it does list the returned sections plus the redaction of national ids. What is missing is limited to edge behavior (record-not-found, pagination or size of policy/address collections), which is minor for a two-parameter getter.

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

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

Schema coverage is 50%: include_activities is documented in the schema, and the description restates it ('when include_activities is true', default false) without adding format detail. individual_id is undocumented in both places beyond the phrase 'by id', so the description only marginally 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 ('One individual by id') and enumerates the payload sections (addresses, policies, custom fields), which separates it from agencybloc_search_individuals and the create/update siblings. It never explicitly names the sibling alternative, but the id-based single-record 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?

Usage is only implied: the tool is clearly the id-keyed fetch, and the include_activities flag hints at the lightweight-vs-full call tradeoff. There is no explicit 'use this when you already have an id, otherwise use search_individuals' routing, and no prerequisites or failure conditions are 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 the safety profile is covered. The description adds the underlying API route and confirms single-record retrieval, but says nothing about behavior when the id is unknown or how much of the record is returned.

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 key. The raw endpoint path is marginally useful telemetry for an agent but borders on filler.

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

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

For a simple one-parameter read tool with no output schema, the essentials are present, but an agent gets no indication of id provenance or failure behavior on an invalid/unknown id, which are the realistic call-time risks.

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

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

Schema coverage is 0% and the single required parameter has no description, so the description must carry the load. Saying 'by record id' clarifies that record_id is the lead's identifier, but it doesn't say where to obtain it, whether it's the internal AgencyBloc id, or what type/format is expected beyond the schema's integer constraint.

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 (one Sales Enablement lead record) and the key (record id), which lets an agent distinguish it from list/search siblings such as agencybloc_search_leads_by_phone. It never explicitly contrasts with siblings like agencybloc_get_individual, but the verb+resource+cardinality 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 use this versus agencybloc_search_leads_by_phone or other get_* tools, and no stated prerequisite (e.g., that record_id must come from a search). The 'POST salesEnablement/Leads/detail' fragment is an endpoint hint, not usage 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, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: it discloses the field set returned (compensating for the absent output schema) and notes the unexpected transport, "POST policies/detail," which tells the agent a read is performed via POST. It does not state behavior for a nonexistent or unauthorized policy id.

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

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

Two short fragments, resource front-loaded, with zero filler. The field enumeration and the API endpoint note both earn their place given no output schema exists, though the telegraphic style is slightly harder to parse than a full sentence.

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

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

For a one-parameter read tool with annotations covering the safety profile, the definition supplies the essential missing pieces: the returned field set and the underlying endpoint. Only not-found behavior and where to source a policy_id are unaddressed, which are minor gaps.

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

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

Schema description coverage is 0% for the single policy_id parameter, so the description carries the burden. "By id" conveys only that the argument identifies the policy; it adds no format, source (where to obtain a policy_id), or error semantics beyond that. Partial compensation for the coverage gap, so a middle score.

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 (get one policy) and scopes it to a single record by id, which distinguishes it from list/search siblings. It enumerates the returned fields (holder, agent, carrier, status, dates, premium, coverages, custom fields) so the agent knows exactly what payload to expect, though it never names search_policies as the 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?

"One policy by id" implies you must already have a policy_id, which is minimal usage context. There is no explicit when-to-use, when-not-to-use, or routing guidance toward agencybloc_search_policies or agencybloc_update_policy, all of which are plausible alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context beyond that: the absence of paging (so the full result set comes back in one call) and the exact fields returned. It stops short of noting auth or rate-limit 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 compact sentences, front-loaded with the resource and scope, then the payload fields and the no-paging constraint. The trailing 'POST activities/list' endpoint note is mild filler but not harmful.

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

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

With no output schema and only two simple params, the description fills the important gap by enumerating the returned fields and stating that results are unpaged. Nothing critical to invoking it correctly is missing, though a note on expected result volume or ordering would complete it.

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

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

Schema coverage is only 50% (entity_id is documented, entity_type only via enum), so the description carries extra burden. It lists the five owning entity kinds (group, individual, agent, carrier, lead), which maps to the entity_type enum, but gives no guidance on the id's origin or how entity_id and entity_type pair up.

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?

State a specific verb+resource ('All activities ... logged on one group, individual, agent, carrier or lead') and enumerate the returned fields, so an agent knows exactly what it retrieves. It does not, however, distinguish itself from the sibling agencybloc_get_activities, which an agent would need in order to choose between them.

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

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

The phrase 'There is no paging' implicitly signals this is the fetch-everything path, but the description never says when to prefer it over agencybloc_get_activities or which entity types are valid inputs. Usage has to be inferred rather than read.

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 adds genuinely new behavioral facts: results are complete in one call ('There is no paging'), ordered 'newest change first', and include an enumerated field set. It omits what an empty result looks like and any cap on result size.

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 field list and ordering up front and the no-paging constraint immediately after; almost nothing is wasted. 'POST notes/list' is transport detail most agents don't need at call time, slightly diluting an otherwise tight description.

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 what each note contains and states that the full list arrives with no paging. For a two-parameter read tool this is close to complete; only empty-result behavior and any practical volume limits are 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?

With 50% schema coverage, entity_id is documented in the schema and the description adds nothing further about it. However, the phrase 'one agent, group, individual or policy' effectively documents the entity_type enum values in prose, partially compensating for that gap. Baseline 3 fits.

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 (notes), the fields returned (subject, body, author, dates, pinned flag, attachment names), and the exact scope (one agent, group, individual or policy), which is specific enough to separate it from the create/get activity siblings. It stops short of naming the obvious alternative (agencybloc_create_note) explicitly, so full sibling differentiation isn't reached.

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: 'on one agent, group, individual or policy' tells the agent the required scope but never states when to choose this over agencybloc_create_note or the get_* tools. The 'There is no paging' line is a useful usage constraint but is not framed as 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds two useful behavioral facts beyond that: the response shape (id, name, email, phones) and the underlying call (POST agents/search, i.e. POST despite being a read). It does not disclose match semantics (exact vs partial, AND vs OR across filters), which matters for a search tool.

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

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

Three short sentences, zero filler, with the search capability front-loaded and the return fields immediately after. Nothing repeats the schema or annotations.

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 one-line return summary ('id, name, email and phones') is genuinely valuable and covers the main gap. However, for a 5-parameter search tool with 40% schema coverage and no required params, the description should state matching behavior and whether filters are ANDed — an agent could otherwise pass an over-broad query and misread the results.

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

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

Schema coverage is only 40% — limit and phone are documented, while email, first_name and last_name have no schema description. The description partially compensates by naming name, email and phone as search keys, but it never explains that 'name' splits into first_name/last_name or how multiple filters combine.

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 ('Search agents') and disambiguates the domain term with '(producers)'. It also enumerates the searchable fields and the returned fields, so it is clearly distinguishable from searches of individuals, groups, or carriers — though it never names a 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: an agent can infer this is the lookup to use when it needs an agent's id before calling agencybloc_get_agent or a create tool. There is no explicit when-to-use/when-not, no prerequisite note, and no routing to alternatives like agencybloc_search_individuals for people who are not producers.

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, openWorldHint=true, destructiveHint=false), so the bar is lower; the description still adds real value by disclosing the return shape (id, name, abbreviation, phones) in the absence of an output schema. The "POST carriers/search" note signals that a read is issued via POST, which usefully pre-empts confusion, though it does not mention result-cap or rate-limit 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?

Three short sentences with the purpose and filters front-loaded, followed by return fields and the endpoint. Nothing is padded or repeated.

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, listing the returned fields is the key missing piece and it is supplied; the 3-param, zero-required schema is largely self-documenting. Minor residual gap: matching semantics (exact vs partial, AND/OR between filters) are not stated.

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

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

Schema coverage is 67%, so the schema already explains limit (1-500, default 50, no paging) and phone matching. The description only echoes the name/phone filters and says nothing about the limit parameter or whether name and phone are ANDed or ORed, so it does not compensate for the remaining 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 ("Search insurance carriers") plus the two filter dimensions (name, phone), and names the returned fields. It is unambiguous against siblings such as search_agents, search_groups, and search_individuals because the resource (carriers) is distinct and no other carrier tool exists.

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

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

The description implies usage by naming the supported filters (name, phone) but never states when to use this versus a get-by-id or list operation, nor does it set exclusions or prerequisites. The critical practical guidance ("no paging: narrow with filters") lives only in the schema, not the description.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the returned field set and the underlying endpoint (POST groups/search), which is useful context, but says nothing about result ordering or that the call is capped with no paging — that only appears in the schema.

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

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

Three terse sentences: what it searches, what it returns, what it calls. Searchable fields are front-loaded and no sentence is filler.

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

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

With no output schema, the explicit return-field list (id, name, type, phone) is exactly the missing piece and is present. A note on result ordering or the practical consequence of the no-paging cap would complete it, but nothing essential for a correct call is absent.

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 60%; type, limit and updated_since are documented in the schema, while group_name and business_phone are bare. The description's "by name, type or phone" maps to three of the five parameters, but it ignores updated_since and limit entirely, so it does not compensate for the coverage gap.

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

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

Specific verb + resource ("Search groups"), plus a clarifying gloss that groups are employer/business accounts, and an enumeration of the searchable fields and returned fields. It is clearly distinguishable from the get_group/create_group siblings, though it never names them.

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 word "search" plus the searchable-field list implies the use case (look up a group when you don't have its id), but there is no explicit when-to-use/when-not guidance and no pointer to get_group for direct id lookups or to search_individuals for people. Usage is inferred 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 and destructiveHint=false, so the safety profile is covered; the description still adds substance by listing returned fields and explicitly noting that national IDs like SSN are never returned, plus what happens with zero filters. Pagination absence is implied but only fully stated in the limit param.

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

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

Four tight sentences with the scope and return payload front-loaded. The trailing 'POST individuals/search' endpoint note is minor but not wasteful.

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 returned fields and the SSN exclusion. The main residual gap for an 8-param search tool is match-mode behavior and ordering guarantees beyond updated_since.

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?

Adds real semantic value with 'filters combine' and the updated_since use case, but leaves the most important search semantics unexplained: whether first_name/last_name/email match exactly or partially. Schema coverage is 63%, and documented params (limit, phone, group_id, updated dates) already carry their own descriptions.

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 ('Search individuals (clients and contacts) in AgencyBloc') and names the underlying endpoint. It is clearly distinguishable from siblings like get_individual (single record) and create_individual.

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?

Explains filter semantics ('all filters are optional and combine; with none you get the first records') and gives a concrete use case ('Use updated_since to find recently changed people'). It stops short of explicitly routing between this tool and get_individual or search_leads_by_phone.

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

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

Annotations already establish that this is a safe read-only search, and the description adds the important prerequisite that only Sales Enablement accounts have lead records. However, it does not describe result format, pagination, or other operational behavior beyond that module constraint.

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 short and front-loaded with the core operation, followed by the module prerequisite and endpoint. It is appropriately sized, though the endpoint notation adds little for tool selection.

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

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

For a one-parameter read-only search with complete schema coverage and annotations, the description provides enough context to invoke it correctly. It could be stronger by mentioning what the search returns, but no output schema exists and the core operational constraints 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?

The sole parameter is fully described in the schema as the phone number to look up, and the description reinforces that the search is by phone only. The description adds little beyond the schema because schema coverage is 100% and there is only one parameter.

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

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

The description uses a specific verb+resource combination: finding Sales Enablement records (leads) by phone number. It also clarifies that the search is phone-only, which distinguishes it from broader lead retrieval such as get_lead.

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

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

It gives clear usage context: use this when searching leads by phone number, and only accounts with the Sales Enablement module contain these records. It does not explicitly name an alternative tool or state when not to use it, so it falls 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the return field list and the POST endpoint, but says nothing about the no-paging/500-cap limit, result ordering, or empty-result behavior beyond what the schema params state.

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: what it searches, what it returns, and one practical usage tip. Front-loaded with the verb and resource, zero 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 usefully enumerates return fields, which is the right compensation. The main omission is the no-paging cap and default limit behavior, which matters for an agent deciding whether one call suffices.

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 82%, so the schema already documents nearly every parameter including the date semantics. The description only echoes the field names and singles out submitted_after/updated_since, adding little semantic detail the schema does not already carry.

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 (Search) and resource (policies) and enumerates the searchable dimensions plus the fields returned, so the agent knows exactly what the tool produces. It implicitly separates itself from agencybloc_get_policy by being a filtered list, but never names that sibling for 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?

'Use submitted_after/updated_since for recent business' gives one concrete usage cue, and 'Search policies by ...' implies filter-driven use. There is no when-not guidance and no explicit pointer to alternatives like get_policy or search_individuals for related lookups.

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, destructiveHint=true, and idempotentHint=true, so the description earns credit for adding genuinely new context: omitted fields are not sent (true partial update, no implicit clearing), the return value is the groupID, and the underlying endpoint is POST groups/update. It stops short of warning that this is a destructive mutation on a shared CRM record or noting whether unintended field wipes are possible.

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 operation class front-loaded as 'WRITE:', followed by semantics and return value.

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 destructive, open-world mutation of a nested-object schema with 12 parameters and no output schema, the description covers the essentials (action, partial-update behavior, return value) but leaves out permission requirements, field-level mutability caveats, and any caution appropriate to destructiveHint=true. Adequate but with clear gaps.

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

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

With only 42% schema description coverage across 12 parameters, the description does some compensating work by establishing that all non-required fields are optional and omitted ones are simply not transmitted — critical for interpreting this schema. However, it adds no meaning for individual parameters (custom_fields keying, account_manager accepting a user id or name, servicing_agent_id), all of which the schema must carry on its own.

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 ('change fields of an existing group') and explicitly scopes it to existing records with partial-update semantics, which cleanly separates it from agencybloc_create_group and the other update_* siblings. The 'including its name' clause also preempts the common question of whether the name is a mutable field.

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 WRITE marker and 'fields you leave out are not sent', which tells the agent how to call it but not when to prefer it over alternatives or what prerequisites (group must exist, correct group_id) apply. No exclusions or cautions are given despite destructiveHint=true.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuine context beyond them: partial-update behavior, that tags are replaced and an empty string clears them, and that individualID is returned. It doesn't explain permission requirements or irreversible effects of tag-clearing beyond the hint, so a 4.

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

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

A single dense sentence cluster with the WRITE marker and entity front-loaded, followed by the field-level caveats and the return value. No filler; every clause conveys a distinct behavioral fact.

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 15-parameter mutation with no output schema, the description covers the essentials: partial-update semantics, the tag-replacement edge case, a scope exclusion, and the return value (individualID). Minor gaps remain around permissions and custom_fields handling, but those are partly covered in the schema itself.

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 40% across 15 parameters, so the description must compensate and only partly does. 'Fields you leave out are not sent' is valuable patch-semantics guidance absent from the schema, but the majority of parameters (email, phones, gender, birth_date, group_id, servicing_agent_id) get no added meaning.

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

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

Opens with an explicit verb and resource ('WRITE: change fields of an existing individual') and the word 'existing' cleanly separates it from agencybloc_create_individual. The endpoint is also stated, removing any ambiguity about what is being modified.

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?

Establishes when/how to use it via partial-update semantics ('fields you leave out are not sent') and a clear exclusion ('Addresses are not changed here'). It stops short of naming a specific sibling tool for address changes or noting prerequisites, so it falls just under 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 destructive=true, idempotent=true and openWorld=true, so the safety profile is covered. The description adds genuinely non-structured behavior: sparse/partial update semantics and that it returns the policyID. It does not discuss permissions, irreversibility of overwritten values, or failure modes.

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 dense sentence, front-loaded with the WRITE marker, then scope, then partial-update semantics and the return value. Nothing is wasted or repeated.

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

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

Given a 15-param destructive mutation with a nested custom_fields object and no output schema, the definition is only just adequate: it covers mutation semantics and the return value, but leaves value domains for status/coverage_type/pay_frequency and clearing-behavior of fields unexplained.

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 60% with 15 parameters, so the description only echoes a handful (status, carrier, dates, premium) already present in the schema. Free-text fields like status, coverage_type, and servicing_agent_id get no value guidance in either place, and custom_fields conventions live only in the schema.

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

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

Specific verb (WRITE/change) plus resource (existing policy) with concrete field examples and the underlying endpoint. It is clearly distinguishable from sibling agencybloc_create_policy and agencybloc_update_group/individual.

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

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

The phrase 'fields you leave out are not sent' clearly frames this as a partial update, which tells the agent how to invoke it correctly. It stops short of naming alternatives (e.g., use get_policy first to read current values) or stating when not to use it.

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