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

No annotations are present, so the description carries the full burden. It clearly discloses that Action Plans are deprecated, which is important behavioral context, and the endpoint plus 'Apply' communicate that this is a write operation. However, it does not describe side effects, idempotency, or response behavior, so gaps remain.

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

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

The description is two sentences with no wasted words. It front-loads the primary action, then adds the deprecation warning and sibling alternatives in a compact, scannable format. 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?

The description covers the essential context: what the tool does, that it is deprecated, and which tools to use instead. With no output schema and no annotations, it could have added a note about the response or side effects, but for an agent deciding whether to call this tool, the provided guidance is strong and sufficient.

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

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

Schema description coverage is 100%, so the parameters are already fully documented in the schema. The description adds no parameter-level detail beyond stating the action itself, which is acceptable given the baseline of 3 for full coverage.

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

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

The description states a specific verb and resource: 'Apply an Action Plan to a person' and backs it with the exact endpoint. It also distinguishes itself from the automationsPerson siblings by explicitly positioning this as the legacy alternative. An agent can tell exactly what this tool does.

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 explicit when-to-use guidance: only when the user names an existing legacy Action Plan. It names the preferred alternatives (create_automations_person, update_automations_person) and states to prefer them for new workflows. This is exemplary routing behavior.

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

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

With no annotations, the description must carry the full burden of behavioral disclosure. It only states 'Create an appointment' and the endpoint, adding nothing about side effects (e.g., sending invitations, admin-only fields), authentication, or response behavior. The schema descriptions for parameters like sendInvitation and createdById carry the behavioral hints, not the tool description.

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

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

The description is a single short sentence, which is concise, but it is essentially a restatement of the tool name and endpoint. It does not front-load any unique value or earn its place; it is minimal to the point of being uninformative.

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 tool with 13 parameters, nested objects, and no output schema, the description is severely incomplete. It lacks any mention of return values, error conditions, required context (like timezone handling), or admin restrictions. The schema and sibling names provide more context than the description itself.

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

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

The schema covers 100% of parameters with detailed descriptions, so the baseline is 3. The tool description adds no parameter-level meaning beyond what the schema already provides, so it neither improves nor degrades the baseline.

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

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

The description clearly states the verb and resource: 'Create an appointment.' This is specific and distinguishes it from read-only tools like get_appointment or list_appointments. However, it does not differentiate from sibling create tools like create_event, which also creates an appointment-like entity, so it lacks explicit 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 description gives no guidance on when to use this tool versus alternatives. It does not mention any conditions, exclusions, or when to prefer create_event or update_appointment. The only clue is the HTTP method, which is not usage guidance.

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

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

With no annotations, the description carries the full behavioral disclosure burden, but it only states 'Create' and the HTTP POST. It does not mention idempotency, required versus optional parameters, success or error responses, side effects, or any constraints like uniqueness of the outcome name.

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

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

The description is two short phrases: a clear action and the HTTP endpoint. It is front-loaded with the verb and resource, contains no filler, and every word 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?

Although the schema covers all parameters, the tool has no annotations, no output schema, and a one-sentence description that omits usage context, behavioral outcomes, or constraints. For a create operation with all-optional fields, an agent would benefit from knowing what happens on success, whether duplicates are allowed, or what the response contains.

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

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

Schema coverage is 100% (all 4 parameters have descriptions), so the baseline is 3. The description adds no parameter-level meaning beyond the schema, but the schema already documents each parameter adequately, including the generic extraBody and extraQuery pass-through objects.

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 clearly states the tool creates an appointment outcome, a specific verb and resource, and the POST endpoint adds clarity. However, it does not explicitly differentiate from sibling tools like list_appointment_outcomes or update_appointment_outcome, relying on the tool name's 'create' prefix.

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 provides no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of conditions or exclusions. An agent is left to infer that this is the create counterpart to list/get/update outcome tools.

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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states the action and HTTP method, without mentioning side effects, required permissions, idempotency, validation behavior, or return value. This is a meaningful gap for a mutation tool.

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

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

The description is extremely concise: one action sentence plus the endpoint. There is no filler or redundancy, and the core purpose is front-loaded.

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

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

The tool has four parameters, nested objects, no annotations, no output schema, and no required parameters listed. The description does not clarify whether name is effectively required, how extraBody/extraQuery behave in practice, or what a successful creation returns. This is incomplete for an agent to invoke correctly with confidence.

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

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

The input schema has 100% parameter description coverage, so the baseline of 3 applies. The description itself adds no parameter semantics beyond what the schema already provides for name, orderWeight, extraBody, and extraQuery.

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 clearly states a specific verb and resource: 'Create an appointment type' with the endpoint POST /appointmentTypes. It is unambiguous about the action, though it does not explicitly differentiate itself from sibling tools like update_appointment_type or list_appointment_types, so it stops just short of a 5.

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

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

There is no guidance on when to use this tool versus alternatives such as update_appointment_type or get_appointment_type. The verb 'create' implies usage, but the description provides no context, prerequisites, or 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?

With no annotations provided, the description carries the full burden of behavioral disclosure, but it reveals nothing beyond the action itself. 'Trigger an Automation' implies side effects, yet the description omits what those effects are, whether the call is idempotent, what permissions are required, or what the response looks like.

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

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

The description is a single sentence with no fluff and a helpful endpoint hint, making it well front-loaded. However, it is so terse that it provides no structural or contextual breakdown beyond the core statement.

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 and no annotation coverage, so the description must carry the completeness burden. It only identifies the action and omits side effects, return behavior, prerequisites, and usage context, making it inadequate for a mutation-like trigger tool.

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

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

Schema description coverage is 100%, and the input schema already documents personId, automationId, extraBody, and extraQuery well. The description adds no parameter-level meaning or examples, so it stays at the baseline 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?

The description states a specific action ('Manually trigger an Automation') and resource ('for a specified Person'), and reinforces it with the endpoint. It clearly communicates the operation's purpose, though it does not explicitly contrast itself with the sibling list/get/update_automations_person tools.

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

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

The use case is implied: use this when you want to manually run an Automation for a Person. However, there is no explicit guidance about when to choose this over sibling tools, no prerequisites like the Person and Automation needing to exist, and no alternatives or 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states 'Add a call' and the endpoint, without covering permission requirements, side effects, required fields, or response behavior. This is minimal disclosure for a mutation tool.

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

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

'Add a call. (POST /calls)' is short, front-loaded, and free of filler. It is concise, though arguably too terse for a 12-parameter creation tool, but the conciseness dimension itself is handled well.

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 creation endpoint with no output schema and no annotations, the description omits operational context such as required fields, admin-only userId behavior, and call outcome semantics. The schema explains parameter meaning, but the description does not provide enough surrounding context for confident invocation.

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

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

Schema description coverage is 100%, so all 12 parameters are already documented and the baseline is 3. The description adds no additional parameter semantics beyond the HTTP method, but it does not need to compensate for missing schema coverage.

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

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

The description uses a clear verb ('Add') and resource ('a call') and includes the HTTP endpoint (POST /calls) for unambiguous identification. It signals creation, distinguishing it from get_call/list_calls/update_call at a basic level, though it does not explicitly name 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?

There is no guidance on when to use this tool versus update_call or list_calls, and no mention of prerequisites such as personId, phone, and isIncoming. The sibling list shows alternatives exist, but the description does nothing to route an agent toward the correct choice.

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 are absent, so the description carries the full burden of behavioral disclosure. It only states the action and endpoint, omitting whether the operation is destructive, what permissions are needed, or that dropdown types require a 'choices' array. It is not misleading but provides almost no behavioral insight.

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

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

The description is a single sentence with no fluff, redundancy, or wasted words, and the endpoint is front-loaded. It is appropriately concise, though so terse that it barely rises above the tool name in informational value.

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

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

With 8 parameters, 2 required, nested objects, no output schema, and no annotations, this description is far too thin. It does not explain that 'choices' is needed for dropdown fields, what the POST response contains, or any operational context. The schema documents fields, but the description fails to provide the contextual glue needed to safely invoke this tool.

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

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

Schema coverage is 100%, with descriptive entries for all 8 parameters including enums, defaults, and notes like isRecurring being date-only. The description adds no parameter-level information, but the baseline 3 applies because the schema already fully documents the parameters.

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

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

The description uses a specific verb ('Create') and resource ('custom field') and includes the exact endpoint, making the action clear. However, it does not distinguish this generic custom field tool from the sibling create_deal_custom_field, so an agent may be unsure whether this creates person-level or deal-level custom fields.

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 like create_deal_custom_field, update_custom_field, or list_custom_fields. No prerequisites, conditions, or exclusions are mentioned, so the agent is left to infer usage from the tool name alone.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only says 'Add a deal', which implies a mutation, but does not disclose side effects, validation requirements, or what happens after creation. It fails to provide any behavioral context beyond the bare action.

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

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

The description is one short sentence, but this is under-specification rather than conciseness. It lacks any structure or front-loading of important information, and every word could be expanded to add value.

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

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

For an 18-parameter tool with no output schema and no annotations, this description is grossly incomplete. It does not explain what a deal is, what the required fields mean in context, any constraints, or what the response looks like. An agent has almost no context beyond the schema.

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

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

Schema description coverage is 100%, so all 18 parameters are documented in the schema. The description adds nothing beyond the schema, which is the baseline for high coverage. It does not clarify parameter relationships or conditional requirements, but the schema already handles basic semantics.

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

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

The description 'Add a deal' clearly states the verb and resource, and it is not a tautology since 'Add' implies creation. However, it is extremely minimal and does not differentiate from related tools like update_deal or get_deal, so it only partially satisfies the dimension.

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. Sibling tools like update_deal, list_deals, and get_deal exist, but the description provides no context about prerequisites, scenarios, or when not to use this tool.

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

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

No annotations are provided, so the description must carry the full behavioral disclosure burden. It only says 'Add' and gives the endpoint; it does not mention side effects, permissions, idempotency, return behavior, or error conditions. This is insufficient for a mutating tool.

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

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

A single clear sentence with the endpoint appended; there is no wasted wording and the core purpose is front-loaded. It is appropriately sized for the minimal information it conveys.

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?

Despite full schema coverage, this is a mutating tool with no annotations and no output schema. The description does not explain the result of the operation, what the response contains, or any behavioral constraints beyond the schema, leaving the agent under-informed.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema. The description adds no parameter-level meaning, so the baseline of 3 applies.

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

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

The description clearly states the action ('Add an attachment') and the resource ('to a deal'), and includes the HTTP endpoint. It distinguishes this creation tool from sibling tools like get_deal_attachment and update_deal_attachment.

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 no guidance on when to use this tool versus get_deal_attachment or update_deal_attachment, nor any context for when adding an attachment is appropriate. The agent must infer usage from the tool name and 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure, but it only restates the creation action and endpoint. It does not mention side effects, authorization needs, the conditional requirement of choices for dropdown fields, or response 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?

The description is a single short phrase plus endpoint, with no filler or redundancy. It front-loads the key action and resource immediately.

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?

Despite 9 parameters, nested objects, no annotations, and no output schema, the entire context is one line. It doesn't mention conditional behavior around dropdown choices, extraBody/extraQuery usage, or related tools, leaving an agent with insufficient context for a create operation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters and the tool description adds no parameter-level meaning. The baseline of 3 applies because the description does not need to compensate for schema gaps.

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

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

The description states the exact action and resource: 'Create a deals custom field,' reinforced by the endpoint 'POST /dealCustomFields.' The word 'deals' distinguishes it from the sibling create_custom_field, so an agent can select it correctly without opening the schema.

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

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

The description gives no guidance on when to use this tool instead of alternatives such as create_custom_field, update_deal_custom_field, or list_deal_custom_fields. There are no when-to-use conditions, prerequisites, or 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?

With no annotations, the description carries the full burden of behavioral disclosure. It reveals only that this is a POST creation operation; it does not mention required context, auth needs, side effects, idempotency, or the shape of the created campaign.

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

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

The description is a single concise sentence with an endpoint, and there is no filler. It is suitably front-loaded, though the brevity leaves little room for context.

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

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

For a mutation tool with no annotations and no output schema, the description should supply more operational context. It lacks alternative selection guidance, behavioral caveats, and expected return information, so it is not complete enough for an agent to use confidently.

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

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

Schema description coverage is 100%, so the baseline of 3 applies even though the description adds no parameter-level detail. It does not clarify how parameters relate to an email campaign beyond what the schema already states.

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

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

The description states a specific verb and resource: 'Create an email marketing campaign' and gives the exact endpoint POST /emCampaigns. It is clear but does not actively differentiate itself from sibling tools such as create_em_event or update_em_campaign.

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 about when to use this tool versus alternatives. The description only offers the operation and endpoint, leaving the agent to infer selection criteria from the name and 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?

No annotations are provided, so the description carries the full burden. It states the action ('Notify') and endpoint, but does not disclose side effects, idempotency, required authentication, rate limits, or what happens on duplicate submissions. The term 'Notify' is vague about whether it creates persistent records or just logs events.

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

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

Single sentence with a clear verb and resource, followed by the HTTP path. No filler words. Efficient and front-loaded.

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

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

No output schema exists, and the description does not explain return values or error behavior. With nested objects and zero annotation coverage, an agent would benefit from knowing prerequisites or confirmation behavior. However, the schema is well-documented, so the main gap is usage context rather than data 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%, so the schema fully documents all parameters including the emEvents array and its nested fields. The description adds little beyond a high-level list of event types in prose, which largely maps to the 'type' enum in the schema. Baseline 3 is appropriate because 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: 'Notify Follow Up Boss' and lists the event types. Includes the HTTP endpoint (POST /emEvents), which disambiguates it from siblings like create_event and create_em_campaign.

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 guidance on when to use this tool vs alternatives like create_event or list_em_events. The description only states the action and endpoint, leaving the agent to infer from tool names and schema. No exclusions or alternative references.

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

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

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses that FUB auto-deduplicates the nested person object, that occurredAt older than 1 day is treated as historical and will NOT trigger routing/automations, and that leaving it unset defaults to now. This goes far beyond what any structured field would reveal.

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

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

The key distinction and usage rule are front-loaded, and the length is justified by the volume of critical behavior. It is somewhat long and includes repeated emphasis, so not a 5, but every major 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 a complex 16-parameter tool with nested objects and no output schema or annotations, the description covers the main behavioral pitfalls (dedupe, routing, historical cutoff, source importance). It does not describe return values, but with no output schema expected and the call-side behavior well covered, it is nearly 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%, so the baseline is 3, but the description adds meaningful selection guidance: type values with 'Registration for a genuinely new lead,' source/system being key for routing, and the critical occurredAt threshold. It doesn't walk through every parameter, but the most decision-critical ones get extra semantics.

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

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

The description opens with a specific action ('Send in a lead or an event related to a lead') and explicitly contrasts itself with create_person, stating this is the actual lead-ingestion event that triggers FUB's routing, automations, and per-source workflows. An agent can immediately distinguish it from create_person and the many create_* 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?

It gives an explicit when-to-use rule ('Use this — not create_person — when a NEW LEAD needs to be registered') and explains why create_person is insufficient. It also warns against backdating occurredAt unless deliberately importing historical data, giving clear do/don't scenarios.

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?

No annotations are present, so the description carries the full burden of behavioral disclosure. It reveals that this is a POST/create operation, but it does not mention side effects, permission requirements, defaults for claimWindow or distribution, whether the operation is idempotent, or what response an agent should expect.

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

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

The description is extremely concise: one short sentence plus an endpoint hint. There is no wasted wording, and the core action is placed up front.

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?

Despite the rich schema, there is no output schema and no annotation coverage description does not state what the API returns on success, how errors appear, or how the extraBody/extraQuery parameters should be used in practice. For a mutation tool with 10 parameters, this is under-specified and requires the agent to infer expected behavior from sibling patterns.

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 baseline of 3 applies. The description itself adds no parameter-level meaning, but the schema thoroughly documents each of the 10 parameters, including defaults, enums, and special constraints such as Lender groups not supporting first-to-claim.

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

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

The description states a specific verb and resource: "Create a new group," with the endpoint reinforcement of POST /groups. It is clear what operation the tool performsaren't distinguished from sibling tools such as update_group or create_team, but the create verb is unambiguous enough for basic selection.

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 about when to use this tool versus alternatives like get_group, list_groups, or update_group. The phrase "Create a new group" only implies the obvious case, and no prerequisites, exclusions, or context for choosing this over related group/team tools are 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?

With no annotations, the description carries the behavioral burden. It discloses a useful non-obvious behavior: FUB does not auto-detect HTML in notes, unlike email templates, and requires isHtml=true. However, it does not cover permissions, side effects, or return value expectations, which leaves some gaps for a mutation tool.

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

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

The description is two sentences with no wasted words. It front-loads the core purpose and then adds the single most important usage caveat.

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 tool with six documented parameters and no output schema, the description plus the fully described schema is largely sufficient to invoke it correctly. It highlights the main gotcha around HTML handling. It could mention return values or prerequisites, but the agent has enough to call the tool accurately.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantic value by explaining when isHtml must be passed and contrasting note behavior with email templates. This goes beyond the schema's simple field description.

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

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

The description states a specific action and resource: "Add a note. (POST /notes)". This clearly distinguishes it from sibling tools like get_note, update_note, and list_notes.

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

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

It provides clear context by stating the tool adds a note and gives a concrete condition for when isHtml must be true. It does not explicitly compare against alternatives, but no alternative create-note tool exists among siblings, and no exclusion criteria are needed.

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?

No annotations exist, so the description must carry the full behavioral burden. It only says 'Create' and gives the endpoint; it does not disclose that personId is effectively required, what response is returned, whether the operation is idempotent, or what side effects occur beyond creating a relationship.

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

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

The description is short, front-loaded with the action, and includes the endpoint for API context. It is efficient, though it sacrifices operational detail that would make it more useful.

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 create tool with 9 parameters, nested objects (emails, phones, addresses), and no output schema or annotations, this description is incomplete. It does not explain the relationship model, clarify required inputs like personId, or describe return behavior, leaving agents to infer critical usage details.

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 has a detailed description in the schema. The tool description adds no parameter-level meaning, but the baseline of 3 applies because the schema already 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?

The description states a specific verb and resource: 'Create a new relationship for a person' and includes the HTTP endpoint. This clearly distinguishes it from siblings like create_person, update_people_relationship, and list_people_relationships.

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

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

The word 'new' implies this tool is for creating rather than updating a relationship, but the description does not explicitly mention alternatives like update_people_relationship or any prerequisites (e.g., personId appears conceptually required but is not marked required). Usage guidance is only implicit.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden, and it does so thoroughly. It warns that deduplicate defaults to false and creates a separate duplicate record, that this tool does NOT trigger FUB lead routing or automations, and that the custom* field is not a literal field name but must be passed via extraBody. These are exactly the non-obvious behavioral traits an agent 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?

Although the description is long, it is dense and every sentence earns its place: endpoint identification, custom-field workaround, duplicate risk, and lead-routing distinction. It is front-loaded with the core purpose and then layers warnings and alternatives in a logical order without tautology or 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 complex create tool with 23 parameters, no annotations, and no output schema, the description covers the most decision-critical context: duplicate behavior, custom field mechanism, and lead vs. person semantics. It does not describe response shape or return values, but that is a minor gap given the strong operational guidance provided elsewhere.

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 baseline is 3, but the description adds practical param meaning beyond the schema. It explains the real-world consequence of the deduplicate default, clarifies how custom fields should be provided through extraBody, and directs the agent to list_custom_fields for exact names. This is meaningful added value over the raw schema.

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

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

The description opens with a precise verb and resource: 'Manually add a new person. (POST /people)'. It also disambiguates this tool from create_event, explaining that creating a person is not the same as registering a lead, which makes the purpose unmistakable among many sibling tools.

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

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

The description gives explicit when-to-use guidance and alternatives: it says to call list_custom_fields first for custom field names, to use get_people_check_duplicate before creating when duplicates are a concern, and to use create_event instead when the user means a new lead rather than a bare CRM contact. This leaves almost no ambiguity about tool selection.

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?

There are no annotations, so the description carries the full burden of disclosing behavior. It only implies a write operation via 'Attach' and 'POST', but does not mention authentication needs, idempotency, duplicate handling, validation, or what is returned on success or failure.

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

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

The description is extremely concise and front-loaded, stating the action and resource in the first phrase. The parenthetical endpoint adds useful reference information without extra filler.

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

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

With no annotationsthor, no output schema, six parameters, and nested objects, the description is too thin. It does not explain return values, the purpose or behavior of extraBody/extraQuery in context, or error conditions, leaving an agent with only the schema to understand the full call.

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 parameters are already documented in the input schema. The description itself adds no parameter-level meaning, which matches the baseline of 3 for high schema coverage.

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

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

The description states a specific verb and resource: 'Attach a file to a person' and reinforces it with the endpoint POST /personAttachments. This clearly differentiates the tool from sibling tools like create_deal_attachment by specifying the person 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 description provides no guidance on when to use this tool versus alternatives such as get_person_attachment, update_person_attachment, or create_deal_attachment. It also omits prerequisites or conditions, such as whether the person must exist or whether the file must already be externally accessible.

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?

No annotations are provided, so the description carries the full burden of disclosure. It only states the basic action and endpoint, without mentioning side effects, required permissions, validation behavior, idempotency, or what happens to nested stages.

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

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

The description is extremely concise: one short statement plus the HTTP method/path. Both pieces of information earn their place, with no filler or redundant wording.

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?

This is a complex tool with 6 parameters, a nested stages object, extraBody/extraQuery escape hatches, and no output schema. The one-line description provides none of the additional context an agent needs, such as response behavior, error cases, or how the extra fields should be used.

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 six parameters. The description adds no parameter-level meaning, but the baseline of 3 applies because the schema already handles 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?

The description states a specific verb ('Add') and resource ('a pipeline'), and also gives the HTTP endpoint (POST /pipelines). This clearly distinguishes it from sibling tools like get_pipeline, list_pipelines, and update_pipeline.

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 no guidance about when to use this tool versus alternatives, no prerequisites, and no exclusions. The verb 'Add' implies a create operation, but the description does not explicitly say 'use this to create a new pipeline, not to update or retrieve one.'

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. "Create a pond" implies a mutating write operation, but it does not describe permissions, side effects, response behavior, or idempotency. This is a significant gap for a create tool with no annotation support.

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

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

The description is extremely concise and front-loaded: "Create a pond. (POST /ponds)". It contains no filler or wasted words. The endpoint is somewhat redundant with the tool name and schema but harmless; the brevity is appropriate given the schema carries most detail.

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

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

For a tool with five parameters, nested objects, no output schema, and no annotations, this description is too thin. It does not explain what a pond is in this domain, the role of userId as lead agent, or what a successful creation returns. An agent cannot fully assess correctness from the description alone.

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

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

Schema description coverage is 100%, so the input schema already documents all parameters including name, userId, userIds, extraBody, and extraQuery. The description adds no parameter meaning beyond the schema, which meets the baseline for fully covered schemas.

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

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

Description states a specific verb and resource: "Create a pond" with the endpoint. This clearly differentiates from siblings like get_pond, list_ponds, and update_pond based on the create action. An agent can tell what the tool does without opening the schema.

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

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

The description gives no guidance on when to use create_pond versus alternatives. It does not mention that create_pond is for new ponds while update_pond handles existing ones, nor does it note prerequisites or conditions. Usage must be inferred entirely from the tool 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?

With no annotations, the description carries the full behavioral burden and only reveals that this is a POST/add operation. It does not disclose whether duplicate reactions are allowed, what authentication or permissions are required, what side effects occur, or what the response looks like.

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

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

The description is one concise sentence that front-loads the action and includes the endpoint for extra clarity. There is no filler and no repetition of schema content.

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 creation endpoint, the description and schema together are mostly usable: required path parameters are identifiable and the body field is explained. However, without annotations, output schema, and a full enumeration of valid reference types are all missing, leaving gaps around response format and allowed values.

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

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

The schema documents body, extraBody, and extraQuery, while refType and refId lack schema descriptions. The description partly compensates by embedding refType/refId in the URL path and giving examples of acceptable refType values, but it does not define refId semantics or constrain refType beyond two examples.

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

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

The description states a specific action ('Add a reaction') and target ('reference data object'), with concrete examples 'Note' or 'ThreadedReply' plus the endpoint POST /reactions/{refType}/{refId}, so the purpose is clear. It is distinct from siblings like create_note or get_reaction, though it does not explicitly contrast with any sibling.

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 or when not to use it. The phrase 'corresponding reference data object' gives only generalized context, but no exclusions, prerequisites, or sibling routing are 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?

No annotations exist, so the description carries the full burden of behavioral disclosure. It only repeats the create action and endpoint, omitting side effects, authorization needs, idempotency, duplicate handling, or response 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?

The description is front-loaded and contains no filler: the purpose is stated first and the endpoint adds useful routing context. However, it is so terse that it misses opportunities to add behavioral guidance.

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

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

With no output schema and no annotations, the description should explain what a successful creation returns and what prerequisites exist. It also does not clarify how stages relate to pipelines or whether extraBody must carry association fields, leaving important invocation context missing.

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

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

Schema description coverage is 100%, so all four parameters, including extraBody, extraQuery, and orderWeight, are already documented. The description itself adds no parameter-level meaning, but the schema covers the necessary 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?

The description uses a specific verb and resource: 'Create a new stage.' The POST endpoint reinforces the creation action and clearly distinguishes this tool from sibling get_stage, update_stage, and list_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?

No guidance is given about when to use create_stage versus alternatives like update_stage or list_stages. The verb 'create' is the only signal, and no when-not-to-use conditions or prerequisites are mentioned.

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

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

The description adds no behavioral insight beyond the name itself; it does not mention side effects, permissions, idempotency, or return behavior. With no annotations to fall back on, the description carries the full burden and fails to disclose anything not already obvious.

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

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

The description is a single, direct sentence with no filler or repetition. It is compact and immediately comprehensible, fully earning its length.

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 11 parameters, conditional requirements, and no output schema or annotations, the one-line description is insufficient for an agent to fully understand the tool's behavior and expected outcomes. The schema covers parameter details, but the description does not address return values or operational context.

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 parameters are fully documented within the input schema. The description itself contributes no additional parameter semantics, hitting the baseline for schema-heavy cases.

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 clearly states the action ('Create') and the resource ('a new task'), and includes the HTTP endpoint for additional precision. It is unambiguous and distinguishes itself from sibling tools like update_task, get_task, and list_tasks.

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

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

No guidance is provided about when to use this tool versus alternatives, nor any exclusions or prerequisites. The description simply states what the tool does without context on when it is appropriate.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that it creates a team, but does not mention required permissions, idempotency, behavior on duplicate names, or return values. For a creation endpoint, these are significant gaps.

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

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

The description is a single sentence with zero wasted words, front-loading the action and including the endpoint. It is appropriately sized for the information it conveys, though that information is minimal.

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 creation tool with five parameters, no output schema, and no annotations, the description is too sparse. It omits critical context such as what the response contains, side effects of creation, whether the operation is idempotent, and any relationship between parameters. The agent would need to infer behavior from the schema and endpoint alone.

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

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

Schema description coverage is 100%, with detailed descriptions for all five parameters. The tool description itself adds no parameter information beyond what the schema already provides, so it meets the baseline of 3 for high coverage without adding extra semantic value.

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 clearly states the action ('Create') and the resource ('a new team'), which is specific and distinguishes it from siblings like update_team, get_team, and list_teams. The HTTP method 'POST /teams' reinforces the creation aspect without ambiguity.

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. It does not mention prerequisites, conditions for choosing create_team over update_team, or any exclusions. The usage context is entirely implied by the verb 'create'.

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

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

With no annotations, the description carries the behavioral burden. It discloses key traits: the tool doesn't substitute merge fields at save time, FUB substitutes them later when a human sends, empty merge fields are left blank rather than erroring, and there is no separate HTML flag. It could additionally mention response shape or auth requirements, but the behavioral core is well covered.

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

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

The description is long, but it is front-loaded with the core purpose and body semantics, then organized into clear merge-field categories. The length is largely justified by the complexity of FUB merge fields; the warning about ambiguous phone fields earns its place. It loses a point because it could be tightened without losing essential guidance.

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

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

Given no annotations and no output schema, this description is unusually complete for invocation: it covers endpoint, required parameters, body format, placeholder behavior, and empty-field edge cases. The main gaps are lack of explicit return-value information and no mention of `isShared` behavior beyond the schema, but those are minor relative to the rich context provided.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes far beyond: it explains that `body` is raw HTML, enumerates the full merge-field vocabulary with contextual warnings about ambiguous phone fields, and describes custom field placeholder conventions. This is exactly the kind of parameter meaning an agent needs beyond the schema.

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

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

The description opens with a specific verb, resource, and endpoint: 'Create a new email template. (POST /templates)'. It clearly distinguishes this from updating templates and from text-message templates by emphasizing email and raw HTML body. Even without reading the schema, an agent knows exactly what the tool does.

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 clearly frames when to use this tool: when creating a new email template via POST /templates. It adds useful guidance by contrasting with notes ('unlike notes, which need isHtml=true explicitly') and by clarifying that this tool only saves text, not sends it. It doesn't explicitly route to sibling tools like update_template or create_text_message_template, but the usage context is clear.

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

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

With no annotations, the description carries the behavioral burden. 'Create a record' makes the primary side effect clear and 'externally sent' suggests no actual SMS is dispatched by this tool. But it does not address permissions, error behavior, or what happens with incoming messages despite the isIncoming parameter.

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 sentence with no wasted words, and the essential purpose is front-loaded. Including the POST path is a compact way to ground the tool in the 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?

The tool is a 9-parameter creation action, and the schema covers parameters well, so the description is minimally sufficient. However, it omits any mention of return value or response behavior, and there is no output schema to compensate, leaving some ambiguity about what the caller should expect.

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 parameters. The description adds no extra meaning about parameter formats, relationships, or usage beyond what the schema already provides, which meets the baseline but does not add value.

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

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

The description uses a specific verb and resource: 'Create a record of an externally sent text message', and includes the POST /textMessages endpoint. This clearly distinguishes the tool from siblings like list_text_messages, get_text_message, and create_text_message_template.

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 'externally sent text message' implies this tool is for logging texts that were sent outside the system rather than for sending new texts. However, it does not explicitly state when to prefer this tool over get_text_message or create_text_message_template, and it offers 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?

With no annotations provided, the description carries the full behavioral burden and succeeds impressively. It discloses that placeholder substitution happens later, that unresolved merge fields are left blank rather than causing errors, that some fields are email-only and meaningless in SMS, that phone versus mobile phone is ambiguous, and that carrier-filtering compliance risks exist. This is far beyond a typical create-tool description.

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

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

The description is long, but the complexity of FUB merge fields justifies most of the length. It is well organized by category (Contact, Company, Agent, Inquiry, etc.), front-loads the core create action and key deferral behavior, and uses warnings and examples to make the dense content scannable. It could be trimmed, but it earns its length.

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 text-template creation tool with no output schema and 5 parameters, the description covers virtually everything an agent needs: merge field syntax, per-context behavior, custom-field lookup guidance, privacy-relevant phone distinctions, compliance best practices, and URL handling. The only minor omission is the API response shape, but that is not critical for a create operation and no output schema is expected.

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?

Although schema coverage is 100%, the description dramatically enriches the semantics of the `message` parameter with a complete merge-field reference, examples, caveats, and compliance guidance. It also clarifies custom-field naming pitfalls and warns about ambiguous phone fields, adding meaning that the schema alone could never convey.

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

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

The description opens with a specific verb and resource: 'Create a text message template. (POST //textMessageTemplates)'. The repeated 'text message template' framing and the texting-specific compliance guidance clearly set it apart from generic sibling tools like create_template or merge tools.

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

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

The description establishes clear context: this is for creating a template, not sending it, and it explains what the tool does not do ('FUB substitutes when a human actually sends the template — not by this tool'). It does not explicitly name sibling alternatives like update_text_message_template, but the creation scope and endpoint make the usage context unambiguous.

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

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

No annotations are provided, so the description must carry the full burden. It discloses the action ('subscribe') but does not describe side effects, idempotency, response behavior, or any requirements (e.g., authentication, rate limits). For a creating tool, this is a minimal 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?

The description is extremely concise: 'Subscribe to a new webhook. (POST /webhooks)' – six words, front-loaded, with zero filler. It efficiently conveys the core action and endpoint.

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 tool with no annotations, no output schema, and four parameters including open object fields (extraBody, extraQuery), this description is too sparse. It doesn't explain the response format, how to handle the extra raw fields, or any behavioral caveats, leaving the agent under-informed for correct invocation.

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

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

Schema description coverage is 100%, and each parameter already has a descriptive schema definition. The tool description adds no parameter-level information, so the baseline of 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?

The description states a specific verb ('Subscribe') and resource ('new webhook'), and the HTTP method POST clarifies it is a creation endpoint. This clearly distinguishes it from siblings like update_webhook, list_webhooks, or get_webhook.

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

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

The word 'new' implies this is for creating a webhook, and the sibling names suggest there are update/list/get variants. However, the description gives no explicit guidance on when to choose this over alternatives, no prerequisites, 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?

No annotations are provided, so the description carries the full burden. It only says 'Retrieve an appointment by id', which implies read-only but doesn't disclose any side effects, required permissions, error behavior, or response format. For a simple GET it is minimally acceptable, but it fails to add any context beyond the action itself.

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 sentence with the endpoint included, front-loaded and free of fluff. It is appropriately sized for a simple retrieval operation; no unnecessary detail dilutes the message.

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, no annotations, and incomplete parameter coverage, the description leaves out essential context. It doesn't mention what the response contains, that extraQuery can be used for custom filters, or any limitations. For a tool with a nested object and sibling retrieval tools, this is insufficient for an agent to call it correctly without external knowledge.

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

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

The description mentions only 'by id', which is already visible in the schema as the required 'id' property. It does not explain the format or purpose of id, and completely omits the optional 'extraQuery' parameter, which has schema coverage only at 50%. Since schema coverage is low and the description adds no parameter meaning, it fails to compensate.

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

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

The description states a clear action ('Retrieve') and a specific resource ('an appointment by id'), and even includes the HTTP endpoint. However, it doesn't differentiate from sibling retrieval tools like get_event or get_call, though the name itself is explicit. It is slightly redundant with the tool name but adds the id-based intent.

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 usage guidance is provided beyond the obvious retrieval-by-id action. There is no mention of when to use this vs. alternatives (e.g., list_appointments when id is unknown), nor any exclusions or conditions. The context implies usage but doesn't state it explicitly.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It states 'Retrieve' which implies a read-only operation, but it does not disclose potential behaviors such as 404 handling, auth requirements, rate limits, or what fields are returned. The description adds little beyond the obvious semantics of a GET-by-ID request.

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

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

The description is a single concise sentence with the key information front-loaded. Including the HTTP endpoint is a small, useful addition. There is 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 a simple get-by-ID tool, the description is minimally viable: it names the resource and the lookup key. However, with no output schema and no annotations, it leaves the return shape and error behavior unspecified. Given the extraQuery parameter and the generic nature of the schema description, more contextual detail would help an agent invoke this correctly, but the tool is simple enough that the description is adequate but 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 only 50% (the 'id' parameter has no description in the schema). The description repeats 'by ID' but adds no new meaning about the parameter's format or source. The extraQuery parameter is already documented in the schema, and the description does not clarify how it applies to this specific endpoint. Since the description must compensate for the incomplete schema coverage and does not, this is a significant gap.

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

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

The description states a specific verb and resource: 'Retrieve an appointment outcome by ID'. This clearly distinguishes it from sibling tools like list_appointment_outcomes (list), create_appointment_outcome (create), and update_appointment_outcome (update). The HTTP endpoint reinforces the intent without ambiguity.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention that you should use it when you already have a specific appointment outcome ID, nor does it reference list_appointment_outcomes for searching without an ID. The usage context is only implied by the phrase 'by 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?

No annotations are provided, so the description carries the full burden. It discloses the HTTP method (GET) and resource path, which implies a read operation, but it does not describe error behavior, authentication requirements, or what happens if the ID does not exist. The description adds minimal behavioral context beyond the endpoint itself.

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

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

The description is a single sentence that is concise and front-loads the core action. It includes the HTTP endpoint, which is useful but slightly redundant with the tool name. No wasted words, though it could have used the space to add usage guidance.

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-by-ID tool, the description is minimal but not entirely inadequate. However, with no annotations, no output schema, and an undocumented 'id' parameter, an agent lacks information about expected return values, error cases, and parameter format. The sibling list_appointment_types suggests this is part of a CRUD family, but the description does not clarify how this tool fits.

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

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

Schema description coverage is 50%: the 'id' parameter has no description in the schema, and 'extraQuery' has a detailed description. The tool description does not explain the 'id' parameter format or that it is the appointment type identifier, though the endpoint path implies it. The 'extraQuery' parameter is well-documented in the schema, so the description adds little beyond what the schema already provides.

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

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

The description states a specific verb ('Retrieve') and resource ('appointment type by ID'), and includes the HTTP endpoint (GET /appointmentTypes/{id}) which makes the operation unambiguous. It doesn't explicitly distinguish from sibling tools like get_appointment or list_appointment_types, but the resource and ID-based lookup are clear enough.

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

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

No guidance is provided about when to use this tool versus alternatives. The description does not mention that list_appointment_types should be used for browsing or that get_appointment is for individual appointments, not appointment types. An agent must infer usage from the name and endpoint alone.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the HTTP method 'GET,' which implies a read operation, but it does not describe the response format, error behavior, authentication requirements, or any side effects. This is minimal coverage for a tool with no structural safety hints.

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

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

The description is a single sentence plus the endpoint, with no filler or redundancy. It is front-loaded with the action and resource, and every token contributes to identifying the tool.

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

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

Given the absence of annotations and output schema, plus the presence of a nested extraQuery parameter and many automation-related siblings, this description is too thin. It does not clarify what an Automation is, what the response looks like, how extraQuery applies here, or when this tool should be preferred over list_automations or get_automations_person.

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

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

Schema coverage is only 50%, and the description adds little beyond clarifying that 'id' is the identifier used in the URL. The extraQuery parameter is left to the schema's generic description, which gives examples for /people or /deals but no automation-specific context. The description does not compensate for the uncovered 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?

The description states a clear verb and resource: 'Retrieve an Automation by ID,' reinforced by the explicit 'GET /automations/{id}' endpoint. It is unambiguous about what the tool does and the 'by ID' scope helps distinguish it from list-style tools, though it does not explicitly differentiate from siblings like list_automations or get_automations_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?

No usage guidance is provided. The description does not say when to use this tool versus list_automations, nor does it mention alternatives or conditions for choosing a different automation-related tool. The agent is left to infer usage from the endpoint alone.

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

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

No annotations are provided, so the description must carry the burden of behavioral disclosure. It only says 'Retrieve' and shows a GET endpoint, which implies a read operation, but it does not disclose possible missing-resource behavior, permission requirements, or how extraQuery interacts with the request. This is minimal rather than informative.

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

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

The description is a single sentence plus endpoint reference, with no filler. Every word contributes to identifying the operation and the path.

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 by-id retrieval tool, the description plus schema is minimally sufficient to attempt a call, since the only required input is the id. However, without annotations or usage guidance, an agent still lacks guidance on behavior, alternatives, or expected edge cases. It is adequate but thin.

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

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

The schema describes extraQuery but not the required id parameter, giving 50% coverage. The description only echoes the endpoint placeholder 'id' without explaining what the id refers to beyond 'pairing. It does not compensate for the undocumented required parameter.

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

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

The description names a specific verb ('Retrieve') and a specific resource ('Automation-Person pairing'), with an explicit endpoint. This clearly distinguishes it from siblings like get_automation, get_person, and list_automations_people, which concern different resources.

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

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

The description gives no guidance about when to use this tool versus alternatives such as list_automations_people, create_automations_person, or update_automations_person. Usage is only implied by the name and endpoint, with no exclusions or alternative routing.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states a read operation ('Retrieve') without detailing any potential side effects, authentication requirements, rate limits, or error behavior. For a tool with no annotation coverage, this is a significant gap.

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

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

The description is a single, front-loaded sentence with no extraneous words. It efficiently conveys the core purpose and includes the HTTP endpoint for extra context, earning a perfect score for conciseness.

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 get-by-id operation with one required parameter, the description suffices to invoke the tool. However, without an output schema and no annotation hints, an agent lacks information about return format, error conditions, or authentication requirements. The description is adequately minimal but not complete given the absence of structured metadata.

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

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

The description references the 'id' parameter ('by id') but adds no additional meaning beyond the schema. The extraQuery parameter is covered in the schema but not mentioned in the description. Given 50% schema coverage, the description does not compensate for the unaddressed 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?

The description clearly states the action ('Retrieve a call') and the resource ('by id'). It is unambiguous and distinguishes from other get tools by specifying 'call'. However, it doesn't explicitly differentiate from similar list or search tools, though the intent is obvious.

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 provides no guidance on when to use this tool versus alternatives like list_calls or update_call. It lacks any mention of prerequisites, context, or conditions that would help an agent decide between this and other call-related operations.

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?

No annotations are provided, so the description carries the full burden. It only says "Get," implying a read, but does not disclose idempotency, error behavior, permissions, or whether the resource could differ from related custom-field tools. It adds no meaningful behavioral context beyond the action itself.

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

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

The description is a single, efficient sentence with the endpoint appended as a useful reference. No filler or redundant wording; it is front-loaded with the primary action.

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 this simple read operation with a required id and an optional extraQuery parameter, the description covers the core action but lacks any behavior/usage context. It is minimally viable: an agent can infer the basic call, but would still need schema details for extraQuery and would not know about error cases or alternative 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?

The phrase "by id" clarifies that the id parameter is a resource identifier, which the schema does not describe. However, the extraQuery parameter is left entirely to the schema, and with only 50% schema coverage the description could have done more to explain how to use it or when it might be needed. This is adequate but minimal.

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 and specific: "Get a custom field by id" states a direct verb and resource, and the endpoint (GET /customFields/{id}) confirms the target. It distinguishes from list_custom_fields by specifying a single id, but does not explicitly contrast with get_deal_custom_field, which is a sibling with a similar 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 usage guidance is provided. The description only states what the tool does, not when it should be used over alternatives like list_custom_fields or get_deal_custom_field, nor any context about common scenarios or required prerequisites.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It discloses the HTTP method GET, signaling a read-only operation, but it does not describe the return payload, potential errors, permissions, or rate limits. That is minimal but adequate for a simple fetch-by-id tool.

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

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

The description is a single concise sentence with the endpoint included. It has no filler and front-loads the core behavior immediately.

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 straightforward by-id retrieval with no output schema, stating the endpoint and required id is sufficient for invocation. It does not explain response fields, but that is not strictly necessary for a GET-by-id operation. The context is complete enough in context of its simplicity.

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

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

Schema coverage is 50%; the id parameter itself has no schema description, so 'by id' at least connects it to the deal resource. The extraQuery parameter is already well documented in the schema, and the description adds no further parameter meaning. This is adequate but not enriching.

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

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

The description states the exact operation: retrieve a single deal by id, and includes the endpoint GET /deals/{id}. This is clear, specific, and easily distinguished from list_deals (listing a collection) and update_deal (a mutation).

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 this is the correct tool when a deal identifier is already known, as opposed to searching or filtering via list_deals. However, there is no explicit when/when-not guidance or mention of alternatives, so it relies on 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 are absent, so the description carries the full burden of behavioral disclosure. The embedded HTTP method 'GET /dealAttachments/{id}' hints at read-only semantics, which is some value. However, it says nothing about auth/permission requirements, 404 or error behavior for missing ids, rate limits, or whether the response contains metadata versus binary content — significant gaps for a fetch operation.

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 short sentence with zero filler, front-loaded with the action verb and resource. The HTTP endpoint hint is a compact, useful addition. Nothing in the description 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 simple get-by-id operation with two parameters, the core action is adequately stated. But with no output schema, no annotations, and no behavioral description, an agent cannot know what the tool returns, how to handle a missing id, or what extraQuery filters actually do to the fetch. Adequate for invoking, incomplete for confident correct use.

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

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

Schema coverage is only 50%; the required 'id' parameter has no schema description and the tool description adds only 'by id' to clarify it is the lookup key. The extraQuery parameter is already well-documented in the schema with an example, so the description adds no value there. The description does not fully compensate for the undocumented id parameter.

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

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

The description states a clear verb+resource ('Get a deal attachment by id') so an agent knows the operation. It implicitly distinguishes from siblings like create_deal_attachment, update_deal_attachment, and get_person_attachment via the verb and 'deal' scope, but it never explicitly names or contrasts those siblings, so differentiation is left to inference.

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

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

No guidance on when to use this tool versus alternatives (e.g., get_person_attachment for person attachments, or list_deals to find an id first). No preconditions, no when-not-to-use, and no exclusions are stated. The agent must guess when this tool is the right choice among the 100+ 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?

With no annotations, the description carries the disclosure burden. It reveals the HTTP method (GET) and that the operation is a read, but it says nothing about permissions, error behavior, or response format. The endpoint and 'by ID' provide minimal behavioral context without fully disclosing 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?

The description is a single sentence plus the endpoint, with no filler or duplicated information. Important scoping information (by ID) is front-loaded, and the endpoint adds precision without bloating the 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 a simple 2-parameter GET tool, the description is minimally sufficient, but there is no output schema and the description does not state what the response contains or any error/edge-case behavior. It also lacks the sibling differentiation needed to make context fully complete.

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

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

Schema coverage is 50%: extraQuery is documented in the schema, while id is not. The description's 'by ID' adds a small amount of meaning by indicating the id parameter is the target custom field's identifier, but it does not compensate for the missing id docs or explain how extraQuery relates to the operation.

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

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

The description uses a clear verb ('Get') and a specific resource ('a deals custom field'), and the endpoint path clarifies it targets a single custom field by ID. It doesn't explicitly distinguish itself from sibling get_custom_field or list_deal_custom_fields, so it isn't a 5, but there is no ambiguity about the operation's core purpose.

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

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

No guidance is given about when to use this tool versus either get_custom_field or list_deal_custom_fields, nor any prerequisites or context. The only implied usage is retrieving one custom field if the caller already has an 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?

No annotations are provided, so the description carries the full burden. It discloses the HTTP method (GET) which implies a read-only operation, but it does not state what happens if the id is not found (404 vs empty), whether the response is a single object or wrapped, or any rate-limit/auth behavior. For a simple read tool this is a moderate gap.

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

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

One sentence, front-loaded with the action and resource, and includes the HTTP endpoint as a compact disambiguator. 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 single-resource GET with one required parameter, the description plus schema is mostly sufficient. However, with no output schema and no annotations, an agent is left guessing about the return shape and error behavior. The extraQuery parameter is well-documented in the schema, so that gap is covered. Overall adequate but 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 50%: the 'id' parameter has no description beyond its type, and 'extraQuery' has a detailed description. The tool description adds no parameter-level meaning beyond the schema. The 'id' parameter's semantics are implied by the description ('by id'), but the schema already names it. Baseline 3 is appropriate because the schema covers half the parameters and the description clarifies the id's role.

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

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

The description states a specific verb ('Retrieve'), a specific resource ('a single event'), and the identifier ('by id'). It also includes the HTTP endpoint (GET /events/{id}), which disambiguates it from sibling tools like list_events, get_call, and get_task. This is a clear, distinct purpose.

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: call this when you need one event by its id, versus list_events for multiple events. However, it does not explicitly state when to prefer this over alternatives, nor does it mention any exclusions or prerequisites (e.g., event must exist, id required). The context is clear but not 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?

With no annotations provided, the description carries the behavioral disclosure burden. The GET method and the verb 'Retrieve' make the read-only nature clear, which is valuable. However, the description does not disclose what happens on missing ids, the response format, or any pagination/query behavior beyond the endpoint.

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

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

A single, front-loaded sentence states the action and the endpoint with no filler. It is appropriately sized for a simple retrieval operation.

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 get-by-id tool, the description plus schema covers the essential call mechanics: the HTTP method, the resource, and the required id parameter. It is slightly incomplete because it does not clarify how this relates to list_groups or get_groups_round_robin, but nothing critical is missing for making a basic successful call.

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

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

The description adds no meaning to the parameters. The schema already documents extraQuery in detail, but the required 'id' parameter has no semantic explanation beyond its type, and the description does not compensate for that gap. With only 50% schema description coverage, parameters are only partially clarified.

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

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

The description states a clear verb ('Retrieve'), resource ('group'), and lookup key ('by id'), and includes the REST path GET /groups/{id}. It is clear on its own but does not explicitly distinguish itself from sibling tools like list_groups or get_groups_round_robin, so it stops short of a 5.

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

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

No guidance is given on when to use this tool versus alternatives. The description implies that you should use it when you already have a group id, but it never names alternatives such as list_groups or get_groups_round_robin, nor does it mention any exclusion conditions.

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?

No annotations exist, so the description carries the full disclosure burden. It reveals the endpoint and the presence of round-robin data but does not explain pagination, response shape, permission requirements, or whether this is read-only beyond the implied GET.

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 clauses with no filler; the main purpose appears immediately and the endpoint is useful context. Information is compact, though some behavioral details are sacrificed.

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

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

The tool has no output schema and no annotations, so a bare statement that it returns round-robin data is incomplete. An agent is left to guess what the additional data looks like and how list_groups differs beyond naming, especially with a sibling list_groups available.

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 sort, type, and extraQuery well. The description adds no param-level detail, but it does not need to; 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?

Clearly identifies the operation with a specific verb ('Lists groups') and a distinguishing feature ('includes round-robin data'), reinforced by the endpoint '(GET /groups/roundRobin)'. It is distinct from sibling list_groups by that feature, though it could more explicitly contrast the two.

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

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

No guidance on when to choose this tool over list_groups or other listing tools. The description implies use when round-robin data is needed, but does not state exclusions or 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?

With no annotations, the description carries the full burden, but it only states that this is a read operation returning identity/authentication information. It does not disclose what the response contains, whether authentication credentials are required, or any potential side effects or limitations.

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

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

The description is extremely concise with no filler. The verb, resource, and endpoint are front-loaded, and every fragment adds useful 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 simple read-only tool with no required parameters, the description is minimally sufficient. However, the lack of an output schema and any behavioral detail means an agent cannot predict exactly what identity or authentication information will be returned.

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

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

The schema provides full documentation of the single optional parameter, extraQuery, including its purpose and behavior. The description adds no parameter-specific details, so the baseline score of 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?

The description clearly states the operation and resource: 'Get identity and authentication information' and includes the HTTP endpoint '(GET /identity)'. This is specific and not a tautology, though it does not explicitly differentiate itself from siblings like get_me or get_user.

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

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

No guidance is provided about when to use this tool versus alternative identity-related tools such as get_me, get_user, or list_users. The description states what the tool does but gives no context for selection or 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the operation is a retrieval, which implies read-only, but it does not disclose behavior like whether only certain participant types are returned, permission requirements, pagination, or what happens if the conversation has no participants. The bare HTTP path is weak compensation for the missing annotation safety profile.

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

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

The description is a single, compact sentence with the HTTP endpoint included for reference. It is front-loaded with the verb and resource, and every word earns its place. It could arguably be shorter by omitting the endpoint, but the endpoint is useful disambiguation for API-fluent 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 simple GET tool with three parameters, the description is thin. There is no output schema and no annotations, so the description must convey what the agent should expect: the shape of returned participant data, any pagination, or relationship to the sibling POST variant. It only covers the basic operation, leaving the agent to guess at response format and edge cases.

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

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

Schema description coverage is only 33%: inboxAppId and extConversationId have no parameter descriptions, and the description text does not explain their semantics beyond the URI template. The extraQuery parameter is well described in the schema, so that parameter carries itself, but the two required identifiers are opaque. The description adds no meaning for the two most important parameters.

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 clearly states the action ('Retrieves participants') and the specific resource ('an Inbox App conversation'), and the HTTP path adds precision. It is distinct from the sibling post_inbox_apps_conversations_participants, which would add participants, so purpose is clear and 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?

There is no explicit guidance on when to use this tool versus siblings like post_inbox_apps_conversations_participants or update_conversation. The HTTP method GET implies a read operation, but the description does not state this is for viewing participants only, nor does it mention any prerequisites (e.g., inbox app must be installed/conversation must exist).

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

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

With no annotations, the description carries the full behavioral burden. It discloses that this is a read-only 'Lists' operation and includes the GET endpoint, which is useful. However, it does not mention authentication, scoping edge cases, pagination, or what an 'installation' entails.

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

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

The description is one focused sentence that front-loads the purpose and appends the endpoint for disambiguation. There is no filler or repetition.

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

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

Given the tool's simplicity, the description conveys the core operation and return concept (installation(s) and ID(s)). However, with no annotations, no output schema, and incomplete parameter semantics, an agent still lacks some context about response shape and edge behavior.

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

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

Schema coverage is only 50%, and the required publishedInboxAppId has no schema description. The tool description only marginally compensates by referencing 'your Published Inbox App' and showing the endpoint placeholder; it does not clearly define the parameter's meaning or the extraQuery behavior beyond what the schema already says.

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

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

The description clearly names the operation ('Lists') and the specific resource ('Inbox App installation(s) and ID(s)') scoped to the current FUB account's Published Inbox App. It is understandable on its own, though it does not explicitly distinguish itself from related inbox-app siblings like post_inbox_apps_install.

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

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

No guidance is given about when to use this tool versus alternatives, nor when not to use it. The phrase 'for your Published Inbox App' hints at context, but there are no exclusions, prerequisites, or sibling comparisons to help an agent choose confidently.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a read operation ('Retrieve') but does not explicitly state it is read-only, nor does it mention authentication, rate limits, or error behavior. It adds little beyond the endpoint itself, leaving agents to infer the operational profile.

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

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

The description is a single concise sentence, front-loading the core purpose. It includes the endpoint in parentheses for reference without unnecessary verbosity. Every word earns its place.

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

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

For a simple tool with one optional parameter and no required fields, the description is minimally sufficient. However, it omits any details about the response format, authentication implications, or potential errors. Given the lack of an output schema and annotations, a bit more context about expected behavior would make it more complete, but the tool's simplicity keeps it at a moderate level.

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

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

The description does not mention the extraQuery parameter at all, but the input schema provides a detailed description of it. Since schema coverage is 100%, the schema adequately explains the parameter. The description adds no additional semantic value beyond what the schema already provides, matching the baseline for high coverage.

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

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

The description states a specific verb ('Retrieve'), resource ('information about the currently authenticated user'), and endpoint ('GET /me'). This is clear and distinguishes it from siblings like get_user, which targets a specific user. The tool name reinforces the 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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, authentication requirements, or situations where get_user or list_users would be more appropriate. The description is purely a statement of function with no usage 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?

With no annotations, the description carries the behavioral burden. 'GET /notes/{id}' and 'Retrieve' convey a read-only fetch, which is useful, but there is no mention of response shape, auth or error behavior, or default inclusions/exclusions beyond what the schema already states.

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

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

The description is one short sentence with an endpoint parenthetical and no filler. The most important scope information ('by id') is front-loaded, and every word earns its place.

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

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

For a straightforward GET with well-documented optional parameters, the essentials are present. However, with no output schema and no annotations, the description never addresses return content or any special behavior, leaving a noticeable but not severe 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 coverage is 75%, and the schema already documents extraQuery, includeReactions, and includeThreadedReplies in detail. The description only adds 'by id' for the otherwise undocumented id parameter, which is marginal, so the baseline 3 applies.

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

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

The description states a specific verb ('Retrieve'), a resource ('note'), and the selection key ('by id'), and it adds the HTTP endpoint for precision. The 'by id' qualifier distinguishes it from list_note/create_note/update_note siblings even without naming them explicitly.

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

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

The phrase 'by id' gives clear invocation context: use this when you have a note identifier and want a single note. It does not explicitly name alternatives or exclusions, but the id qualifier is sufficient for basic routing among the sibling tools.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses that this is a GET-style check operation, which implies a safe, read-only behavior. However, it does not explain matching semantics, response format, or behavior when no identifier parameters are supplied.

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

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

The description is one concise sentence plus the endpoint reference, with no wasted words or filler. The core purpose is front-loaded and the API path is a useful, non-redundant addition.

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

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

The tool has no output schema and no annotations, yet the description does not explain what the duplicate check returns or whether at least one of email/phone is required. Given all parameters are optional in the schema, this could lead an agent to make an invalid or meaningless call.

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 three parameters clearly. The description itself adds no parameter-level meaning, so baseline 3 is appropriate. The extraQuery parameter is well explained in the schema with an example.

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

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

The description states a specific action ('Check whether a person exists') and names the exact endpoint it maps to, which clearly identifies the tool's purpose. It does not explicitly differentiate itself from sibling tools like get_person or list_people, though the name and endpoint imply a distinct duplicate-check behavior.

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 no guidance on when to use this tool instead of get_person, list_people, or create_person, and no context about when duplicate checking is appropriate. It also does not mention prerequisites such as requiring an email or phone number before calling.

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?

No annotations are provided, so the description carries the burden. The 'GET' method makes the read-only behavior clear, but the description does not disclose response shape, error behavior, auth requirements, or how extraQuery affects results.

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, information-bearing sentences with no filler. The action and endpoint are front-loaded and immediately usable.

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-resource GET with only one required parameter and an extraQuery fallback documented in the schema, the description is nearly sufficient. It could be improved by naming sibling alternatives, but nothing essential is missing for basic invocation.

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

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

The description adds the fact that id is a path parameter via the endpoint template, which the schema does not explicitly say. extraQuery is well documented in the schema itself, so the description does not need to repeat 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 and resource: 'Get a specific relationship' plus the exact endpoint. The word 'specific' distinguishes it from list_people_relationships, and the resource itself separates it from create/update relationship tools.

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

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

Usage is implied: use this when you need one relationship by ID, rather than listing relationships. But it does not explicitly name alternatives or state when not to use it.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It openly discloses a notable deviation from the API default: it sets limit=100 (FUB's max) rather than the underlying default of 10, and explains the intent ('bulk requests are the common case here'). It also describes the pagination contract, telling the agent to check _metadata and use offset or the _metadata.next cursor. This is substantial and useful transparency, though it does not explicitly state read-only behavior or any rate-limit/authorization implications.

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 sentences, no wasted words. The first is a clear purpose statement, the second explains the default-limit override with a rationale, and the third provides actionable pagination guidance. Every sentence earns its place, and the most important information is front-loaded.

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

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

For a simple list endpoint with no output schema and three optional parameters, the description gives the essential operational context: what it returns, the altered default, and the pagination mechanics. It does not describe the shape of each returned lead object, but that is likely standard for the API. It also leaves extraQuery usage to the schema alone, which already has a clear description. Overall, the description covers the most important contextual needs for an agent to invoke the tool 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?

All three parameters are already described in the input schema (100% coverage), which sets the baseline at 3. The description adds practical meaning to two of them: it explains why limit defaults to 100 and when to use offset (when _metadata shows more results). This goes beyond the schema's dry definitions. However, it does not mention extraQuery at all, leaving that entirely to the schema description, so it does not fully elevate beyond the baseline.

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

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

The description opens with a specific verb-resource pair, 'Get unclaimed leads,' and reinforces it with the API endpoint (GET /people/unclaimed). The qualifier 'unclaimed' cleanly differentiates this from sibling tools like list_people (which retrieves all people) and post_people_claim (which modifies ownership). An agent can immediately understand what the tool does and how it differs from nearby alternatives.

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 no explicit guidance on when to prefer this tool over siblings such as list_people, get_person, or post_people_claim. It mentions that bulk requests are common, but that is a default-behavior note, not tool-selection advice. There is no 'use this when...' or 'use this instead of...' framing, leaving the agent to infer the usage context from the name alone.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that this is a GET/read operation and hints that full records are the default unless reduced via `fields`. However, it does not mention response shape, error behavior for missing IDs, or permission requirements, which would be valuable for a tool with no annotation safety profile.

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

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

Three terse sentences, each earning its place. The primary action is front-loaded, the endpoint is embedded naturally, and the two follow-up sentences provide pragmatic guidance without filler.

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

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

For a simple read-by-id tool with no output schema and only three parameters, the description covers the core invocation path and even advises on optimizing payloads and handling custom fields. A minor gap is the absence of any expected return shape or error semantics, but given the tool's simplicity and the guiding notes, it is substantially 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 67%, and the description adds meaningful semantics beyond the schema: it explains why `fields` exists (request only what you need, avoid full records) and warns that custom field names must be discovered via list_custom_fields rather than invented. This goes beyond the schema's bare parameter type descriptions.

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

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

The description opens with a specific verb + resource ('Retrieve a person by id') and includes the exact endpoint (GET /people/{id}). This clearly distinguishes it from siblings like list_people (collection), update_person (mutation), and get_person_attachment (different resource).

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 explicit guidance on when to use the `fields` parameter ('when scanning many people') and instructs calling list_custom_fields first to discover exact field names rather than guessing. It does not explicitly name alternative tools for this action, but the context is clear enough to route an agent.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action and endpoint, without mentioning whether the operation is read-only, any authorization requirements, error behaviors, or what the returned attachment object contains. This is a significant gap for a tool that mutates nothing but still needs 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?

The description is appropriately brief and front-loads the primary action and resource. It is a single sentence with the endpoint appended, containing no redundancy. However, it omits necessary contextual details, so it is concise but not fully functional.

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 tool with two parameters (including a nested object), no output schema, and no annotations, this description is incomplete. It does not explain what an attachment is, how 'extraQuery' is used, what the response format is, or any special behavior. The agent would have to infer too much, making the description insufficient for confident invocation.

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

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

The tool description adds virtually no parameter meaning beyond the schema. The schema already lists 'id' and 'extraQuery', with 'extraQuery' fully described. The description only says 'by ID', which adds little to the schema's explicit parameter list. Given schema coverage is only 50% (no description for 'id'), the description should compensate but does not.

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 clearly states the action ('Retrieve') and the resource ('an attachment by ID'), with an explicit endpoint. It is unambiguous about what the tool does, but it does not differentiate itself from sibling tools like get_deal_attachment or get_evidence, relying on the name for context.

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, nor any mention of prerequisites or contextual conditions. The description is purely functional and offers no direction on selecting it among similar retrieval tools, leaving the agent to infer usage.

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?

No annotations are provided, so the description carries the full burden. It only states the HTTP method and resource, which is essentially the same as the tool name. It does not disclose what happens if the id is not found, whether related objects are included, or any response characteristics. For a read operation, this is a minimal but not rich 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?

The description is a single sentence with the endpoint included, which is efficient and front-loaded. It earns its place by adding the HTTP method and path, though it is terse. 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 get-by-id tool, the description is minimal. There is no output schema, no annotations, and no mention of error behavior or response format. The sibling list is large, and the description does not help an agent distinguish when to use get_pipeline vs list_pipelines. The endpoint is helpful, but the description lacks enough context for an agent to know what to expect.

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

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

Schema description coverage is 50%: the 'id' parameter has no description, while 'extraQuery' has a detailed description. The description adds no parameter-level meaning beyond the schema. The 'extraQuery' parameter is well explained in the schema, but 'id' is left to the tool name and endpoint. Baseline 3 is appropriate because the schema covers half the parameters well.

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

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

The description states a specific verb ('Retrieve') and resource ('pipeline by id'), and includes the HTTP endpoint (GET /pipelines/{id}) which clarifies the operation. It is distinguishable from siblings like list_pipelines and update_pipeline, though it doesn't explicitly name them.

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

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

The description implies usage: use this when you have a pipeline id and need a single pipeline. It does not explicitly state when to use list_pipelines instead, nor does it mention any prerequisites or context. The endpoint hint provides some context but no exclusions or 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?

No annotations are provided, so the description must carry behavioral disclosure. It does indicate the HTTP method (GET) and scoping by id, which implies a read-only exact-match retrieval, but it does not mention error cases (e.g., 404) or response shape. For a simple getter this is minimally adequate.

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

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

The description is a single concise sentence with no filler, and the endpoint is included parenthetically for immediate context. Every word 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?

Given the simple read operation, the description plus schema covers the essential parameter (id, with the endpoint), and extraQuery is documented in the schema. Missing details like error handling or return format are not covered, but there is no output schema and the tool is straightforward.

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

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

Schema description coverage is 50%; only extraQuery is described. The description adds meaning to the 'id' parameter by stating the tool retrieves 'by id', but it does not elaborate on id format or extraQuery. The schema already documents extraQuery, so the description provides marginal value beyond the schema.

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

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

The description uses a specific verb ('Get) and resource ('pond), and specifies retrieval by 'id', clearly distinguishing it from list_ponds (which lists multiple ponds) and from other resource getters like get_event or get_call. The endpoint '(GET /ponds/{id})' reinforces the 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 description clearly implies the tool is for retrieving a single pond when an id is available, which is the context for use. However, it does not explicitly contrast with list_ponds or other alternatives, and provides no exclusion criteria.

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

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

With no annotations, the description must carry behavioral weight. It does indicate this is a GET, implies read-only behavior, and discloses a performance trait (no Redis fan-out). However, it doesn't mention response shape, whether the call counts against rate limits, or any authentication requirements.

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

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

The description is compact, front-loaded with the resource identity, and uses the endpoint and sibling comparison efficiently. Every sentence adds value with no redundancy.

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

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

For a simple read-only endpoint with one optional parameter, the description covers what the tool returns conceptually and why to prefer it. The absence of an output schema is a minor gap, but the tool's purpose and differentiation are sufficiently clear.

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% for the single parameter, so the schema already documents extraQuery. The description adds no parameter-level detail, which is acceptable given the high schema coverage, so baseline 3 applies.

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

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

The description names the exact resource ('currently-configured rate limits') and gives the endpoint path. It also distinguishes itself from get_rate_limit_usage by clarifying this is about configured limits, not usage.

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

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

It provides concrete selection context by stating this endpoint is cheaper than /v1/rateLimit/usage and why (no Redis fan-out). It doesn't explicitly say 'use usage when you need actual consumption data,' but the contrast is clear enough to guide tool choice.

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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It indicates a read-only GET operation and a 24-hour time window, but it does not describe response format, error conditions, authentication, or pagination 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?

The description is one concise sentence plus the endpoint path, and the most important information is front-loaded. Every element earns its place without redundancy.

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

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

For a simple read-only tool with no required parameters and a fully documented schema, the description provides the essential semantics: what the tool reports and which endpoint it hits. It is slightly incomplete only because it does not disambiguate from get_rate_limit_limits or describe 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% for the single optional extraQuery parameter, and that parameter is already documented with an example and clarification of pass-through behavior. The description itself adds no parameter detail, so the baseline score of 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?

The description states a specific resource (rate limit usage), the HTTP method, and the concrete data it returns: 24-hour request volume, rate-limit hits, and configured limits. It is clear in what the tool does, though it does not explicitly differentiate itself from the sibling get_rate_limit_limits.

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 usage guidance is provided. The description does not say when to prefer this tool over get_rate_limit_limits or any other alternative, nor does it mention prerequisites or call context.

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