Teamgate MCP by usefulapi

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-redundant behavior: the note is permanently uneditable and undeletable through this toolset, plus the underlying POST /events endpoint, which pairs with the non-idempotent hint. It stops short of saying whether the target entities must exist or what happens on invalid IDs.

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

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

Two short sentences with the WRITE flag and the primary purpose front-loaded, followed immediately by the durability constraint. No filler, no restated schema fields.

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

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

For a write tool with no output schema and full annotation coverage, the description supplies the essentials: what it does, that it is a POST, and that it is irreversible. The one gap is the mismatch between required parameters (text only) and the description's 'one or more' targets, leaving the minimum valid call ambiguous.

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

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

Schema description coverage is 100%, so every parameter including text and the three id arrays is already documented, making 3 the baseline. The phrase 'one or more leads, companies or deals' adds the useful nuance that multiple entities across types can be targeted in a single call, but the schema also permits zero targets (only text is required), which the description does not clarify.

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 ('add a note') and the resources it attaches to (leads, companies, deals), and marks it as a write up front, so an agent can place it immediately. It does not address how it differs from the sibling teamgate_create_activity, which posts to the same underlying events resource, so sibling differentiation is only partial.

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 note's irreversibility ('cannot be edited or removed with these tools') implicitly tells the agent this is for one-shot annotations rather than tracked work, which weakly guides usage. However, there is no explicit when-to-use versus teamgate_create_activity, and no statement of prerequisites such as needing at least one linked entity.

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/destructive/non-idempotent/open-world, so the bar is lower. The description adds genuinely new behavioral context beyond those flags: that Teamgate may send reminders to the owner (an external side effect) and the underlying POST /events endpoint. It does not address duplicate creation, which matters given idempotentHint=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?

Two tightly packed sentences with zero filler; the 'WRITE:' prefix front-loads the operation class and the endpoint is appended as a useful trailer. Slightly dense but every clause carries information.

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

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

For a 9-parameter create tool with no output schema, the description covers the nature and side effects of the call but omits required-field expectations, failure behavior, and what is returned (e.g., the new activity id used by teamgate_get_activity). Adequate but with clear gaps for a mutation entry point.

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

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

Schema description coverage is 100%, with per-field descriptions and constraints, so the schema carries the parameter burden. The description's 'optionally linked to leads, companies or deals' merely restates lead_ids/company_ids/deal_ids without adding format, limits, or interaction rules. 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 ('create a task, call or appointment') and enumerates the type enum values, so the agent knows exactly what is produced. Implicitly distinguishes from the get/list siblings by the create verb, but never names a sibling for explicit contrast.

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

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

There is no when-to-use guidance: nothing says when to create an activity versus using teamgate_add_note or teamgate_update_* tools, and no prerequisites (auth scope, owner requirements) are given. The linking mention hints at context but does not route the agent between 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=false, destructiveHint=true, idempotentHint=false, so the 'WRITE:' prefix merely restates structured data. The description omits real behavioral context such as whether duplicate companies are rejected or merged, and whether side-effect entities (source/industry auto-creation noted only in schema) cause extra writes.

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 fragments with no wasted words, but the size reflects under-specification rather than economy, and 'POST /companies' is low-value transport detail for an agent. It is front-loaded, so structure is acceptable.

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

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

A 10-parameter mutation tool with no output schema and no description of the created record, required permissions, or error/duplicate behavior. Annotations cover only the safety profile, leaving meaningful gaps for an agent to call it correctly on the first try.

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

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

Schema description coverage is 100% and every parameter is documented inline, including enum-like values for customer_status and cross-references like teamgate_list_users. The description adds nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('create') and resource ('company') plus the HTTP endpoint, so the operation is unambiguous. It does not differentiate itself from sibling creators like teamgate_create_person or teamgate_create_deal beyond the resource name.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites (e.g., required auth or owner lookup), and no note on duplicate handling. The agent must infer everything from the name.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false, so the agent knows this is a non-idempotent write. The description's only behavioral content is the 'WRITE:' prefix, which merely restates readOnlyHint=false and adds no new information about permissions, side effects (e.g. source auto-creation), or reversibility.

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, operation type front-loaded, zero filler. It is arguably over-compressed for an 11-parameter write tool, but nothing in it is wasted.

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

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

For a write tool with 11 parameters and no output schema, the description omits what the call returns (deal id?), what side effects occur (source record creation), and what authorization or prerequisites are needed. The schema carries the parameter burden, but post-invocation expectations are left entirely 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% and all 11 parameters are documented in the schema, so the baseline is 3. The description only echoes the buyer_id concept, adding no syntax, defaults, interdependencies, or format notes beyond the schema.

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

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

States a specific verb and resource ('create a deal') and clarifies the relational target ('for a buyer (a person or company)'). It is distinguishable from update_deal and get_deal, but it does not differentiate itself from the other create_* siblings beyond the resource name.

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

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

No when-to-use guidance, no prerequisites (e.g. that buyer_id must reference an existing person or company record), and no pointer to alternatives such as teamgate_update_deal for modifying an existing deal. 'POST /deals' is endpoint trivia rather than 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 disclose readOnlyHint=false, destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: creating a lead may trigger Teamgate workflows or notifications, a side effect the agent cannot learn from annotations.

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

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

Three short clauses: the write/verb statement, the key input constraint, and the side-effect note, capped by the endpoint. Front-loaded, no filler, every sentence earns its place.

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

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

For an 11-parameter create tool with no output schema, the description covers the operation, the essential input rule, the side effect, and the endpoint, while annotations cover safety. It stops short of telling the agent what a successful response returns or how the new lead id is surfaced, but otherwise it is complete enough to call 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 100%, so the schema already documents all 11 parameters with lengths and the name/company_name mutual requirement. The description restates the name-or-company_name rule but adds no syntax, format, or defaulting details beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('WRITE: create a lead') and clarifies that a lead may be keyed on a person's name or a company_name, which hints at the polymorphic record type. It does not, however, distinguish this from the sibling write tools teamgate_create_person or teamgate_create_company, leaving the agent to infer which create_* to call.

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 invocation guidance ('Give a person's name, or a company_name for a company lead') and implies the create-record context via 'POST /leads'. It offers no when-to-use/when-not or alternative-selection guidance against the many sibling create tools, so usage remains 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=false and destructiveHint=true, so the 'WRITE:' prefix and 'POST /people' largely restate the safety profile. The only incremental behavioral content is the optional company/job-title linkage, and even that overlaps the job_title schema text ('used only together with company_id'). No note on side effects like source/industry records being silently created.

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

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

Two short sentences; the write nature and resource are front-loaded, with the optional linking detail second. Slightly telegraphic ('WRITE:', trailing endpoint) but no wasted text.

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

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

For an 11-parameter create tool with no output schema, the description tells the agent what it creates and the one cross-entity relationship, while the rich schema covers the rest. It omits what the call returns (created person id) and any note that some fields auto-create related records (source, industry), leaving 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 100%, so the schema already explains all 11 parameters including the company_id + job_title dependency and enum-like customer_status values. The description adds only a high-level summary of the linking relationship, which is the correct baseline-3 posture when the schema does the heavy lifting.

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

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

States a specific verb+resource (create a person/contact) plus the endpoint (POST /people), which cleanly separates it from create_company, create_deal, and create_lead in the sibling list. It does not explicitly name or route against siblings, but the resource noun makes the distinction unambiguous.

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

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

No indication of when to use this versus teamgate_update_person (for existing records) or teamgate_create_company, and no prerequisites such as needing company_id/owner_id resolved first. The optional company-link behavior is mentioned but not framed as a usage condition or exclusion.

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 without description help. The description adds only the endpoint hint (GET /events/{id}) and the entity taxonomy, but says nothing about pagination, not-found behavior, or what the returned payload contains.

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

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

Two short sentences, front-loaded with the core purpose and followed by scope details, with zero filler or redundancy. Every clause carries information the agent can act on.

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

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

For a single-parameter, read-only lookup with annotations covering safety, the description is nearly sufficient. The one gap is that no output schema exists, so the shape of the returned activity is never described anywhere; otherwise nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single parameter activity_id is fully documented in the schema, so the baseline is 3. The description's 'by id' restates rather than enriches the schema's meaning and adds no format or range guidance beyond it.

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

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

States a specific verb+resource ('One activity ... by id') and enumerates the entity types covered (task, call, appointment or note), so an agent immediately understands the return is a single activity record keyed by id. It implicitly contrasts with teamgate_list_activities but never names any sibling to make the distinction explicit.

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

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

The phrase 'by id' hints that the caller must already possess an activity id, which is the only usage signal present. There is no statement of when to prefer this over teamgate_list_activities or teamgate_list_record_activities, and no prerequisites or error conditions are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only 'with all its details', which hints at a complete payload but does not describe the shape, error behavior on a missing id, or any rate limits.

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

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

Two short sentences with the key information front-loaded and no filler. The endpoint path is mildly redundant with the tool name but does confirm the exact API surface.

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 two-parameter read with full schema coverage and annotations carrying the safety profile, the description is largely sufficient. The only real gap is that 'all its details' leaves the returned fields unspecified, and no output schema exists to fill that in.

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 company_id and include_custom_fields are already documented in the schema, including the default of false. The description adds nothing about either parameter; baseline 3 applies.

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

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

States a specific verb and resource ('Get company' / 'One company by id') and restates the underlying endpoint GET /companies/{id}. It is clearly a single-record fetch rather than the sibling teamgate_list_companies, though it does not name that sibling explicitly.

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

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

'by id' implies the tool applies when a company id is already known, which distinguishes it from list/search siblings by inference. No explicit when-to-use, when-not-to-use, or named alternative is provided.

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 without description help. The description adds the shape of the returned record and the API path, but says nothing about error behavior for a missing/invalid id or about permissions.

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

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

Two short sentences, zero filler, with the primary purpose front-loaded and the endpoint as a secondary detail. Slightly telegraphic phrasing ('one deal by id with value, stage...') reads as a field dump rather than fully grammatical guidance, but nothing is wasted.

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

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

With no output schema, the description usefully enumerates the key fields a caller can expect. Combined with readOnly annotations and a fully documented 2-parameter schema, an agent has enough to invoke this correctly; only error/permission behavior is unstated.

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% – both deal_id and include_custom_fields are documented in the schema, including the default for include_custom_fields. The description adds nothing beyond what the schema already states, so the baseline 3 applies.

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

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

States a specific verb+resource ('One deal by id') and enumerates the returned facets (value, stage, status, owner, buyer, dates) plus the underlying endpoint. An agent can distinguish it from teamgate_list_deals, but the description never names the sibling alternatives 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?

'by id' implies the tool is for single-record retrieval when the id is already known, which is a reasonable implicit signal against teamgate_list_deals or teamgate_search. However, there is no explicit when-to-use statement, no prerequisites, and no mention of what to do when the id is unknown.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the raw REST path but nothing about error behavior for an unknown id or response shape beyond 'all its details', so it meets the minimum with annotations carrying the load.

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

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

Two short sentences, zero filler, with the core purpose front-loaded before the endpoint path. Nothing in it 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?

For a simple single-record read with full annotation coverage and a fully documented schema, the description is adequate; 'all its details' summarizes the return in the absence of an output schema. It could still note behavior for a missing id, which keeps it out of the top score.

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%: lead_id and include_custom_fields are both documented in the schema, including the default for custom fields. The description adds no syntax or format detail beyond 'by id', so the baseline 3 applies.

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

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

The description gives a specific verb+resource ('One lead by id') and states the scope (single record, all details), which implicitly distinguishes it from teamgate_list_leads. It stops short of naming any sibling explicitly, so it is clear but not fully differentiated.

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 the caller must already have a lead_id, which contrasts with list/search tools. There is no explicit when-to-use/when-not statement and no mention of the sibling list or search tools as 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 fully covered. The description only restates the REST endpoint (GET /people/{id}), which is redundant with readOnlyHint and adds no new behavioral context such as error behavior for a missing id or the cost of the openWorld lookup.

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

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

Two short sentences with zero filler; the core purpose (one person by id) is front-loaded and the endpoint acts as a compact identifier. Nothing needs trimming.

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

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

For a simple read tool with full schema coverage and annotations covering the safety profile, the description is minimally sufficient. It is thin on what 'all their details' actually returns and on failure modes, but nothing critical to correct invocation is missing.

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

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

Schema description coverage is 100%, so both person_id and include_custom_fields are already documented in the schema. The description adds no syntax, format, or default information beyond it, which is the baseline case for a fully covered 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 with scope: fetch a single person by id, returning full details. It implicitly separates itself from teamgate_list_people and teamgate_search by the 'one person by id' framing, but never names those siblings explicitly.

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

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

The phrase 'One person by id' hints at when to use it (single-record lookup), but there is no explicit guidance on when to prefer this over teamgate_list_people, teamgate_search, or teamgate_list_company_people, and no mention of prerequisites such as needing a valid id.

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, openWorldHint=true, so the safety profile is covered. The description does add one real behavioral fact beyond annotations: the response includes the pipeline's stages. It says nothing about authorization needs or error behavior for a nonexistent 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, front-loaded with the resource and scope; nothing is padded. The trailing raw endpoint path is mildly redundant with the name and schema but cheap and grounding for API-aware agents.

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 schema coverage and no output schema, the description tells the agent what is fetched and that stages are included, which is enough to call it correctly. Only the absence of guidance about an unknown id keeps it from being 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 single parameter is described there as 'Teamgate pipeline id.' The description's 'by id' adds no format, range, or source-of-value detail beyond the schema, so the baseline 3 applies.

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

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

States a specific resource ('One sales pipeline') and retrieval key ('by id'), plus the scope ('with its stages'). The singular framing implicitly contrasts with the sibling teamgate_list_pipelines, but it never names that alternative, 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?

The phrase 'by id' implies a lookup when the pipeline id is already known, but there is no explicit when-to-use, when-not-to-use, or pointer to teamgate_list_pipelines for discovery. The agent must infer the routing itself.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the raw REST endpoint ('GET /users/{id}'), which restates the operation rather than disclosing anything new such as not-found/error behavior, auth requirements, or rate limits.

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

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

Two short fragments with zero padding, and the scope ('One ... by id') is front-loaded. The trailing endpoint string is mildly redundant with the tool name but efficient.

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

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

For a one-parameter read tool with full schema coverage and no output schema, the description is minimally sufficient, but it says nothing about the returned user shape, invalid-id handling, or how it relates to teamgate_list_users. Adequate, not complete.

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

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

Schema description coverage is 100% and the single user_id parameter is documented as 'Teamgate user id.' with an exclusiveMinimum of 0. The description's 'by id' simply mirrors the schema and adds no format, source, or constraint detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('One Teamgate user by id') and implies single-record retrieval, which distinguishes it from the parallel teamgate_list_users sibling. It is clear, though the differentiation from list_users is only implied by 'One ... by id' 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?

There is no explicit when-to-use guidance, no prerequisites (e.g., needing a valid user id), and no alternative named. The agent must infer from the name that this is the lookup path when an id is already known versus listing users.

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 by structured data. The description adds only the underlying endpoint (GET /events) and the definition of an activity; it says nothing about pagination behavior, result caps (limit max 100), or volume of returns, which a listing tool would benefit from disclosing.

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

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

Two short sentences, zero padding, with the resource definition front-loaded. The trailing 'GET /events' is endpoint trivia of marginal value, but it 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?

Reasonable for a low-complexity, zero-required-parameter read tool, and no output schema exists so return values need not be described. However, the description never addresses pagination or how results relate to the per-record activity listing sibling, leaving a modest gap for a tool whose schema is entirely pagination-focused.

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

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

Schema description coverage is 100% with only two well-documented pagination parameters (limit, offset with next_offset guidance), so the schema carries the full burden. The description adds no meaning beyond it; baseline 3 is appropriate.

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

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

States a specific verb (List) and resource (activities), and enumerates the subtypes it covers (tasks, calls, appointments, notes), which removes ambiguity about what an 'activity' is. It scopes the operation to 'across the account' but never names or distinguishes itself from the closest siblings, teamgate_list_record_activities and teamgate_get_activity.

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?

'Across the account' implies an account-wide listing as opposed to the record-scoped sibling teamgate_list_record_activities, but the distinction is left for the agent to infer. There is no explicit when-to-use, when-not-to-use, or prerequisite 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 by structured data. The description contributes the HTTP method/path (GET /companies) but adds nothing about pagination behavior, result caps, or response shape beyond naming the fields 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?

Three tight sentences/clauses, front-loaded with the resource and its returned fields before the filter list. Efficient, though the field enumeration and filter list partially overlap in concept.

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

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

For an 11-parameter read-only list tool with no output schema, the description covers both what can be filtered and what fields come back. Pagination is handled in the schema (offset/limit with next_offset guidance), so the description is largely complete for correct invocation; only alternative-tool routing is missing.

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

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

Schema description coverage is 100% and each parameter already carries its own semantics (partial-match rules, min lengths, default limits, next_offset usage), so the schema does the heavy lifting. The description restates the filter dimensions without adding format or constraint detail beyond what the schema provides.

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

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

States a specific verb and resource ('List or search companies') and enumerates the returned fields (owner, industry, source, status, contact details) plus filterable fields. It is clear what the tool does and is distinguishable from teamgate_get_company, though it never explicitly contrasts itself with the plural siblings teamgate_search or teamgate_list_company_people.

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 filter list implies when to reach for this tool (broad retrieval by name/email/phone/owner/VAT/date), but there is no explicit when-to-use vs when-not guidance and no pointer to teamgate_search for keyword queries or teamgate_get_company for single-record lookups. Usage is inferable but not 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 contributes nothing beyond that – no pagination behavior, no note on what a company with no people returns, no auth or rate-limit context.

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

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

Two short sentences, front-loaded with the purpose and free of filler. The endpoint sentence is largely redundant with the description and schema, keeping it just short of ideal.

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 paginated list tool with no output schema, the description says nothing about the shape of returned person records or how paging results should be consumed (though the offset parameter hints at next_offset). Annotations cover safety, so the gap is moderate rather than severe.

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 company_id, limit, and offset are fully documented in the schema (including the helpful 'Pass the previous reply's next_offset' note). The description adds no parameter meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb ('List') plus resource ('people') and scopes it to 'one company', which implicitly separates it from the broader teamgate_list_people sibling. It does not name that sibling explicitly, and the trailing 'GET /companies/{id}/people.' restates the resource rather than adding meaning.

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 infers it should call this when it has a company id and wants that company's contacts, versus teamgate_list_people for a global list. There is no explicit when-to-use, when-not-to-use, or prerequisite (e.g., valid company_id) 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 only the endpoint routing (GET /people/{id}/deals vs /companies/{id}/deals); it says nothing about return volume, pagination behavior, or empty results beyond what the offset schema note implies.

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

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

Two tight sentences, front-loaded with the purpose and followed by the endpoint mapping. Nothing is wasted, though the endpoint line is proximity-to-redundant with the operation name for an agent that already knows the resource.

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

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

For a simple read-only list tool with no output schema and fully documented parameters, the definition supplies enough to invoke it correctly; safety is covered by annotations. The one gap is any statement about result shape or that pagination is available, which the schema only obliquely covers via next_offset.

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% – limit, offset, contact_id, and contact_type are all documented in the schema (including the next_offset pagination hint and the enum for contact_type). The description adds no parameter meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb+resource ('List the deals') plus the exact scoping ('that belong to one person or one company'), and even supplies the REST endpoints. This clearly separates it from the sibling teamgate_list_deals, which lists deals without a contact scope.

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 scoping phrase implies when it is appropriate (you have a person or company id and want its deals), but there is no explicit when-not and no alternative named (e.g., use list_deals for all deals, or search for filtered queries). Usage is inferable rather than directed.

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 only that the listing is account-scoped and read-only in nature (definitions, not values) plus the endpoint path; it says nothing about pagination limits or result size 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?

A single tight sentence with the resource stated first and the returned fields in parentheses. The trailing 'GET /customFields' is mildly redundant but costs little.

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, fully-annotated, zero-required-parameter read tool with no output schema, the description supplies enough: what is listed, that it is account-wide, and which fields come back. Missing only usage context relative to other listing 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 description coverage is 100%, with limit and offset both documented including the next_offset chaining hint. The description adds no parameter detail, so the schema does all the work — the baseline 3 applies.

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

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

Specific verb+resource: 'List the custom field definitions of the account', with the returned attributes enumerated (id, name, type, module). It is clearly distinct from the record-listing siblings like teamgate_list_deals, though it never names a sibling to route against.

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

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

No when-to-use guidance, no mention of alternatives such as teamgate_search, and no conditions or prerequisites. The agent must infer that this is the right tool purely from the resource name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety and scope are covered structurally. The description adds only the HTTP surface ('GET /deals') and the fact that results are filterable; it says nothing about result caps, pagination flow, or rate limits beyond what the schema already encodes.

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: the first front-loads what is returned and how it can be filtered, the second gives the endpoint. No filler, no redundancy, and the most important information (verb + resource + filter surface) comes first.

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

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

For a 10-parameter, no-required-parameter list tool with annotations and no output schema, the description covers what the resource is and which dimensions can be filtered. It partially compensates for the missing output schema by naming the returned fields, but does not describe the paginated response envelope (limit/offset/next_offset) that the schema only hints at.

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

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

Schema description coverage is 100%, so every one of the 10 parameters is already documented in the schema, including pagination semantics ('Pass the previous reply's next_offset') and the stage_id cross-reference. The description merely mirrors a subset of the filter fields and omits limit, offset and include_custom_fields, adding no new 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?

The description gives a specific verb ('List or search') and resource ('deals (sales opportunities)') plus the fields carried in results and the filterable attributes. It implicitly separates itself from teamgate_get_deal (single deal) and teamgate_list_contact_deals, but it never names those siblings, so an agent still has to infer the boundary.

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

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

Usage is only implied: the enumeration of filter dimensions (name, status, stage, owner, source, creation date) suggests this is the filtered collection endpoint, but there is no explicit when-to-use, when-not-to-use, or named alternative such as teamgate_search or teamgate_get_deal. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuine behavioral value by disclosing the return shape (id, name, win probability) and that the deal's current stage is flagged as selected, which is not visible 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?

A single front-loaded sentence followed by the endpoint path. Every clause earns its place: the resource, the returned fields, the selected marker. No filler.

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

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

There is no output schema, so the description usefully compensates by naming the returned fields and the selected-current-stage behavior. Combined with annotations covering the read-only profile and a fully documented single parameter, an agent has enough to call it correctly; only cross-tool routing guidance is missing.

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

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

Schema coverage is 100% and the single deal_id parameter is documented as 'Teamgate deal id.' The description only restates the per-deal scope ('one deal') without adding format, constraint, or lookup guidance beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (List) and resource (pipeline stages of one deal), scoping it to a single deal rather than the pipeline catalog, which distinguishes it from teamgate_list_pipelines and teamgate_get_deal. It also enumerates the returned fields (id, name, win probability) and the selected marker, so an agent knows exactly what it produces.

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

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

Usage is only implied: 'one deal' signals it operates per-deal and requires a deal context. There is no explicit when-to-use vs teamgate_get_deal (which also returns stage info) or teamgate_list_pipelines, and no prerequisites or exclusions 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. The description adds only 'GET /industries', which restates readOnly, and says nothing about pagination behavior or whether the list is account-scoped vs global.

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

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

Two short sentences, purpose front-loaded with zero padding. The trailing 'GET /industries' is redundant with the readOnly annotation 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 zero-required-parameter, read-only reference list with full schema coverage and no output schema, the description is sufficient to invoke the tool correctly. Return contents are only loosely characterized ('industries of the account'), which is a minor gap.

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

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

Schema description coverage is 100%, and the offset parameter already tells the agent to pass next_offset from the previous reply. The description adds no meaning beyond the schema, which is the expected baseline here.

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 the industries of the account'), so the agent knows exactly what it retrieves. It does not differentiate itself from the many other list_* siblings (sources, deal stages, lead statuses), which would all be described the same way.

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 explicit when-to-use, prerequisites, or alternatives are given. Usage is strongly implied by the name and the read-only nature of a reference list, so the agent can infer it, but nothing routes it here versus teamgate_list_custom_fields or teamgate_list_sources.

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 only that results can be filtered and that it hits GET /leads; it says nothing about pagination behavior, result caps, or authentication needs.

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

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

Two compact sentences, front-loaded with the action and resource, followed by capabilities and endpoint. The filter enumeration is slightly redundant against the schema 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?

There is no output schema, so the description would ideally hint at what each lead record returns (the intro mentions owner, status, source, industry, contact details, which partially serves this) but omits pagination/next_offset behavior that the schema only implies. For a 12-parameter list tool it is adequate but not thorough.

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

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

Schema description coverage is 100%, with each of the 12 parameters documented in the schema itself, including defaults and ranges. The description's filter list largely restates those fields and adds no syntax or format detail (e.g. partial-match semantics), so the baseline 3 applies.

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

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

States a specific verb (list/search) and resource (leads), with a helpful parenthetical defining leads as 'unqualified prospects' and an endpoint hint (GET /leads). It does not explicitly name a sibling, but the resource is distinct enough from teamgate_list_people/deals that no confusion arises.

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

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

Usage is implied by the enumeration of filterable fields, but there is no explicit when-to-use guidance, no statement of when this is preferable to teamgate_search, and no mention of prerequisites such as obtaining status or source names first.

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 value beyond that by exposing the underlying endpoint (GET /leadsStatuses) and clarifying the semantic of the returned names as filter values, though it says nothing about pagination behavior or result shape.

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

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

A single front-loaded sentence giving purpose, then a compact usage hint, then the endpoint. Every clause earns its place with no filler.

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

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

For a read-only reference-list tool with full schema coverage, annotations carrying the safety profile, and no output schema, the description supplies what an agent needs. The only minor gap is the absence of any note on pagination despite limit/offset parameters.

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

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

Schema description coverage is 100%, with limit and offset both documented in the schema including defaults and the next_offset convention. The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb and resource: 'List the lead statuses of the account.' The resource is unambiguous and distinct from sibling lookups like list_sources or list_industries, though the description does not explicitly contrast itself against those siblings.

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

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

The parenthetical 'use the names as the status filter or value on leads' hints at how the returned data feeds into filtering leads, which implies the workflow context. However, it never states when to call this tool versus the other list_* reference tools, so usage remains implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the GET /people endpoint and a field list; it does not add richer behavioral context such as result shape or sort behavior. A 3 is appropriate given the annotations carry the main burden.

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

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

Three compact sentences, front-loaded with the core action and filters, with the endpoint tacked on last. No waste, though the trailing 'GET /people' is marginally 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?

No output schema exists, but for a read-only list tool with fully documented parameters the description covers purpose and filtering adequately. Minor gap: it does not mention pagination behavior, which the offset param hints at but the description never surfaces.

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

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

Schema description coverage is 100%, so the schema already documents all ten parameters with types, ranges, and semantics. The description's filter list maps onto existing params but adds no syntax or value details beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (list/search) plus resource (people, clarified as contacts) and enumerates the fields involved. It is distinguishable from list_companies/list_leads by the resource, though it does not explicitly differentiate itself from teamgate_search or teamgate_get_person.

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 filterable dimensions (name, email, phone, owner, customer status, creation date), so an agent can infer how to search. However, it offers no explicit when-to-use guidance versus the search tool or get_person, and no exclusions.

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 real endpoint (GET /pipelines) and, importantly, the return shape (id and name), which matters because there is no output schema. It does not discuss pagination behavior beyond what the schema implies.

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 zero waste; the core purpose is front-loaded and the sibling routing plus endpoint follow.

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

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

With no output schema, the description usefully names the returned fields and the endpoint, which is the main missing structured information. Filtering and pagination are fully covered by the schema, so an agent has enough to call it 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 100% — the schema itself documents name filtering, the 1-100 limit bound, and the offset/next_offset chaining. The description adds no parameter syntax or format detail 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?

Specific verb ('List') and resource ('sales pipelines'), with the returned fields named (id and name). It is clearly distinguishable from teamgate_get_pipeline, which it explicitly routes to for a single pipeline's stages.

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 names the alternative tool and the condition that selects it ('Use teamgate_get_pipeline for the stages of one'), so an agent can choose between listing pipelines and fetching one without opening either schema.

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 structurally. The description adds the REST endpoint and the returned field set, but says nothing about pagination behavior (offset/next_offset semantics) or result ordering, which is the main behavioral gap for a paged list.

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

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

Very short and front-loaded: the resource and returned fields come first, with the HTTP detail last. Nothing is padded, though the 'GET /products' fragment is only marginally useful to an agent that calls tools rather than raw endpoints.

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

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

For a simple, zero-required-parameter list tool with no output schema, the description does supply the return shape (id, name, price) and annotations cover safety. It is nearly sufficient, missing only pagination/ordering context that an agent paging through results would want.

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

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

Schema description coverage is 100%, so name, limit and offset are fully documented in the schema. The description adds no parameter meaning beyond that (it doesn't even mention that name is a partial-match filter). Baseline 3 is appropriate when the schema does all the work.

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

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

States a concrete verb and resource ('List the products of the catalogue') and even enumerates the returned fields (id, name, price) plus the backing endpoint. It does not differentiate from the sibling teamgate_search, which could also surface products, so it falls short of a 5.

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

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

No when-to-use guidance is given at all. The description never says whether this is for browsing the full catalogue versus narrowing by name, nor when to prefer it over teamgate_search or teamgate_list_* siblings.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the concrete activity types (tasks, calls, appointments, notes) and the REST endpoint, which is useful context, but it does not disclose pagination behavior, rate limits, or authentication requirements beyond what annotations provide.

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

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

Two sentences, front-loaded with the purpose. The second sentence supplies the REST endpoint, which is somewhat redundant given the readOnly annotation but still compact and informative. No wasted words.

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

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

For a simple, read-only list tool with 100% schema coverage and no output schema, the description provides sufficient context to invoke correctly. The absence of return-value details is acceptable because no output schema exists, though it could mention pagination cues that the schema already covers.

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

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

Schema description coverage is 100%, so all four parameters are fully documented in the schema. The description adds no parameter-level details beyond restating the record types already enumerated in record_type. Baseline 3 is appropriate when the schema carries the parameter semantics.

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

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

States a specific verb (List) and resource (activities) with clear scope (linked to one lead, person, company or deal). It implicitly differentiates from the unfiltered teamgate_list_activities by requiring a record, but does not explicitly name or contrast with that sibling, so it falls short of a 5.

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

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

The description implies usage (retrieve activities for a specific record) but provides no explicit when-to-use guidance, no when-not-to-use conditions, and does not name alternative tools like teamgate_list_activities or teamgate_get_activity. An agent must infer the appropriate context.

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 nothing beyond restating the HTTP endpoint (GET /sources), which simply duplicates the readOnly annotation rather than contributing new behavioral context such as pagination limits or result shape.

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

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

One compact, front-loaded sentence that leads with the resource and its meaning. The trailing "GET /sources" is slightly redundant with the readOnly annotation but is cheap and harmless.

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

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

For a simple, no-required-parameter list tool this is close to adequate, and pagination is hinted at via the offset schema text. However, with no output schema, the description says nothing about the returned structure (list of source objects, IDs vs names), leaving the agent to guess at the response shape.

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

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

Schema description coverage is 100%: both limit and offset are documented in the schema, including the instruction to pass the previous reply's next_offset. The description adds no parameter meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb (List) and resource (lead/deal sources of the account), and the parenthetical "where records come from" disambiguates the term 'sources'. It is distinguishable from siblings like teamgate_list_lead_statuses and teamgate_list_industries, though it never names those siblings directly.

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

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

There is no guidance on when to call this versus alternatives, no prerequisites, and no exclusions. The agent is left to infer that this is the lookup for source values, which is only weakly implied by 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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real value beyond that: it discloses the returned fields (id, name, username) and the underlying endpoint (GET /users), which matters because there is no output schema.

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

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

Two compact sentences that front-load the purpose and avoid filler. The trailing 'GET /users' is slightly redundant with the tool name but earns a small amount of API-mapping value; the phrase 'filters and values' is a touch ambiguous.

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

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

With no output schema, the description usefully names the returned fields, and the schema fully documents all five optional parameters while annotations cover the safety profile. What remains thin is guidance on pagination interplay and differentiation from teamgate_get_user.

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

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

Schema description coverage is 100%, with each of the five parameters documented in the schema (name, email, limit, offset, is_active), so baseline is 3. The description does not add syntax or semantic detail beyond the schema; the mention of owner_id is about consuming results, not about an input 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?

States a specific verb and resource ('List the Teamgate users of the account') and even names the returned fields (id, name, username). It is clearly distinct from teamgate_get_user in intent, though it never names that sibling explicitly to reinforce the singular-vs-plural distinction.

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

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

Provides downstream usage context ('Use the ids as owner_id filters and values'), which tells the agent what to do with the output, but gives no when-to-use vs teamgate_get_user guidance and no exclusions or prerequisites. 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 the safety profile is covered. The description adds the search scope (name-matched across four modules) and the underlying endpoint, but says nothing about result ordering, caps, or paging behavior beyond what the schema implies.

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

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

Two short sentences, front-loaded with the resource and scope; nothing is wasted. The trailing 'GET /global' is endpoint trivia that adds little for an agent but costs only three words.

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 search with three annotations, a fully described 4-parameter schema, and no output schema, the description covers what the tool does and over what. Return shape/paging is reasonably inferable from the offset/next_offset schema text, so little 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% – every parameter including limit, offset, query, and modules is documented in the schema. The description's 'by name' framing restates what the query schema already says ('Text to find in record names'), 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?

Clear verb (Search) plus the four record types it spans, and it explicitly frames the cross-module scope with 'in one request'. This distinguishes it from the many per-module list_* 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?

'In one request' implies the value proposition (unified lookup vs. per-module list calls), but there is no explicit when-to-use, when-not-to-use, or named alternative such as teamgate_list_leads. Usage context is inferable rather than stated.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered by structured fields. The description adds genuine value beyond them: it discloses partial-update semantics ('only the fields you pass are sent') and the overwrite consequence for those fields, and restates the PUT endpoint consistent with idempotentHint.

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 tightly packed fragments with the mutation flag front-loaded. The overwrite rule is stated before the endpoint, and nothing is wasted or repeated from the 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?

For a 9-param mutation tool with annotations covering safety, full schema coverage, and no output schema, the description is nearly complete. It covers write intent, partial-update behavior, and the endpoint; only error/permission behavior on an invalid id is absent, which is minor here.

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

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

Schema description coverage is 100%, so the schema fully documents all nine parameters including the required company_id. The description adds no syntax, format, or constraint detail beyond the schema, 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 ('change fields of one company') and leads with 'WRITE:' to mark it as a mutation. It implicitly differentiates from sibling update tools by resource type, but never names an alternative (e.g., create_company or get_company), so sibling routing 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?

Usage is implied: an agent understands this updates an existing company. There is no explicit when-to-use vs when-not, no mention of the create/read siblings, and no prerequisites (e.g., needing a valid company_id). The partial-update note leans toward behavior rather than selection 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 write/destructive/idempotent semantics, so the bar is lowered. The description adds genuine value beyond them by clarifying that only passed fields are sent while those fields are overwritten, plus the PUT /deals/{id} endpoint. It omits permission/auth requirements, but the partial-overwrite nuance is a meaningful disclosure.

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

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

Three tight sentences, front-loaded with the "WRITE:" operation label and ending with the endpoint. The overwrite caveat is placed before the URL so critical semantics come first; 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?

For a 12-parameter write tool whose schema has full coverage and whose annotations carry the safety profile, the description covers operation type, partial-update behavior, and endpoint adequately. No output schema exists, so return values need not be explained; only auth/permission notes are 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 description coverage is 100%, so the schema fully documents all 12 parameters and the baseline is 3. The description adds only a light hint by naming stage and won/lost as examples, without new syntax or format detail.

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

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

States a specific verb and resource ("change fields of one deal") and reinforces it with concrete examples (move stage, mark won/lost), which cleanly separates it from create_deal and get_deal. It stops short of explicitly naming siblings, so 4 rather than 5.

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

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

The update examples imply typical use cases but there is no explicit when-to-use/when-not-to-use guidance or direction to alternatives (e.g., create_deal for new records). Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful partial-update semantics — only passed fields are sent, and they overwrite current values — which the annotations do not convey. It omits auth requirements, error behavior, and side effects like source/industry auto-creation (which the schema covers).

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

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

Three short sentences with the operation type front-loaded as 'WRITE:', followed by the key mutation caveat and the endpoint. Nothing is wasted and the most important warning appears early.

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

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

For a mutation tool whose annotations and fully documented schema carry the safety and parameter burden, the description covers what an agent needs to invoke it correctly: scope, partial-update behavior, and endpoint. It could still mention that omitted fields are left untouched versus cleared, which is the main residual ambiguity.

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 all eight parameters are individually documented, including the auto-create behavior for source and industry and the teamgate_list_users pointer for owner_id. The description adds no parameter-level detail 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?

The description gives a specific verb ('change fields') and a specific resource ('one lead'), and the resource name alone distinguishes it from the update_company/deal/person siblings. It stops short of any explicit differentiation or routing language, so it is clear but not maximally sharp.

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?

'WRITE: change fields of one lead' implies the context of use (modifying an existing lead) but never states when to prefer this over teamgate_create_lead, teamgate_get_lead, or the other update_* tools. Usage is implied rather than guided.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value by disclosing the partial-update behavior — only passed fields are sent and they overwrite current values — which is not conveyed by annotations. It does not cover auth requirements, but the extra mutation nuance justifies 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?

Three short clauses: action, method, endpoint. The most important operational caveat (overwrite semantics) is front-loaded and every sentence earns its place.

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

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

For an update tool with full annotation coverage and a fully described schema, the description supplies the key missing context: it is a write and a path-based PUT. The only gap is a light lack of usage routing among dozens of siblings, but the essential calling information is 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 the schema already documents all parameters. The description confirms that supplied fields are overwritten but adds no syntax, format, or constraint details beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (change fields) and resource (one person), and the HTTP endpoint PUT /people/{id} pins it down. It is distinguishable from create_person, but it does not explicitly name a sibling alternative for partial updates.

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 single-record write and the 'only the fields you pass' note helps an agent understand update semantics, but it offers no explicit when-to-use context (e.g., when to use this vs update_company or vs creating a new person) and no prerequisite guidance.

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