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 action and the optional API key behavior, but it does not mention side effects, duplicate behavior, permissions, error handling, or what the mutation returns.

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 and well-structured: a single purpose sentence followed by a focused Args list. Every line adds information, especially the environment fallback for api_key, with no filler.

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

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

For a simple three-parameter tool with an output schema present, the parameter documentation and core action are adequate. However, the lack of when-to-use guidance and side-effect context, combined with zero annotations, keeps it at minimally viable rather than 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 description coverage is 0%, but the Args block provides meaningful semantics for all three parameters: activity_id is the Intervals.icu activity ID, content is the message text, and api_key is optional with an explicit fallback to API_KEY from .env. This goes well beyond the bare schema titles.

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 clear verb+resource combination: 'Add a message (note/comment) to an activity on Intervals.icu'. This makes the tool's purpose unambiguous, though it does not explicitly distinguish itself from siblings like get_activity_messages or add_or_update_note.

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 the tool is for adding notes or comments to an activity but provides no explicit guidance on when to use it versus alternatives. Given the sibling list includes similar tools like get_activity_messages and add_or_update_note, explicit routing guidance is missing.

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?

Without annotations, this carries the full burden. It explains that the tool creates or updates an event depending on event_id, that auth falls back to .env values, and covers workout step behavior in detail. However, it does not say whether an update replaces fields partially or fully, what side effects an update has, or what response to expect, so transparency is incomplete.

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 content is long, but the tool's nested step structure justifies most of it; the opening is front-loaded and the sections (Args, Example, Step properties, How to use) are clearly organized. Some repetition exists in the Step examples, but it does not obscure the essential 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 high complexity and an output schema, this is close to complete: it gives a full example, enumerates step construction patterns, and explains defaults. It falls short on the ambiguous event_id/.env update behavior and the misleading 'many arguments are required' statement, and it leaves some WorkoutDoc fields undocumented, so a few edge cases could trip up an agent.

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?

Input schema has 0% coverage, so the description must compensate, and it does: top-level args get units, defaults, and env fallbacks, and Step properties get examples for power/hr/pace/cadence, ranges, ramps, repeats, and freeride. It is not exhaustive—several WorkoutDoc fields (ftp, lthr, target, locales, options) are absent and 'many arguments are required' conflicts with the schema's two required fields—but it adds substantial meaning.

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

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

The first sentence names the action ('Post event'), the target resource (Intervals.icu), and the audience ('for an athlete'), then clarifies the create-vs-update behavior when event_id is present. This is enough for an agent to distinguish it from sibling event tools like get_events or delete_event.

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 explicitly gives the create/update branch: if event_id is provided, update instead of create, and notes that many arguments map directly to the API. It does not enumerate when to prefer siblings such as delete_event or get_events, but the main decision point is covered.

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 disclosure burden. It says 'Add or update' and notes that event_id is for updates, but does not explain mutation side effects, auth requirements, whether an update without event_id creates a duplicate or errors, or how existing data is affected. This is a material gap for a write-capable tool with no annotation coverage.

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 opens with one clear purpose sentence and then uses a compact argument list with no redundant prose. Each line adds information not inferable from the parameter name alone, and the format is scannable for an agent.

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

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

The description plus output schema covers parameter invocation fairly well, but for a mutation tool with no annotations it leaves gaps around update-versus-create behavior, required auth context, and possible failure modes. The event_id update hint is useful, but an agent still lacks enough context to know what happens when adding a note that already exists or updating with a missing/invalid event_id.

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

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

The input schema has 0% description coverage, so the description must compensate, and it does. Every parameter gets a meaningful natural-language explanation: name and description semantics, start_date format and default, color examples, athlete_id/api_key optionality, and event_id's role in updates. This gives an agent enough to correctly populate arguments.

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 or update') and the resource ('a plain text note (category NOTE) on the Intervals.icu calendar'), using a specific verb and target. It distinguishes itself from sibling tools like add_or_update_event by noting the note category 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 description implies usage for notes via 'plain text note (category NOTE)' and gives update guidance through 'event_id: optional, for updates', but it never explicitly states when to prefer this tool over add_or_update_event or other note/event tools. Usage context is present but not fully developed, and no exclusions or alternatives are named.

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

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

No annotations are provided, so the description carries the full behavioral burden. It states the create side effect and mentions auth fallback via athlete_id/api_key, but it does not disclose constraints, duplicate-name behavior, required permissions, or any failure/validation traits. This is thin 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?

The one-sentence purpose followed by a compact Args list is well structured and front-loaded. But the corrupted content line undermines the clarity, and the list could be tightened without losing 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 7-parameter create tool with an output schema, the description covers all parameter names and several enums, so basic invocation is possible. It is not complete for more complex item types because the required shape of the content dict is under-specified and no guidance addresses conditional requirements.

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

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

With 0% schema description coverage, the description compensates by listing every parameter and adding value: item_type examples, visibility options, env-var fallback for auth, and note that content is a dict. However, the content configuration details are incomplete and the allowed 'type' bullet is garbled/self-contradictory, so it only partially compensates.

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 opening sentence uses a specific verb and resource: create a new custom item for an athlete on Intervals.icu. The word 'new' clearly distinguishes it from the update_custom_item, get_custom_items, and delete_custom_item siblings without needing to inspect their schemas.

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 action is clear but there is no explicit when-to-use guidance or mention of alternatives. An agent can infer that it should be used for creating rather than updating or deleting, but the description relies entirely on that implication.

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 that the tool deletes a custom item, implying destructive effect, but says nothing about irreversibility, permissions, impact on related data, or error behavior. The .env fallback for athlete_id and api_key is a useful behavioral detail, but the overall transparency is thin 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 compact and front-loaded: one clear purpose sentence followed by a tight Args list. Every sentence earns its place, with no filler or redundant 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?

The description fully covers the parameter semantics and the main operation, and an output schema exists, so return values are not required. However, it lacks usage guidance, a permanence warning, and any clarification of what exactly is deleted or not deleted. Given the zero annotations and destructive nature, a few more sentences would make it complete.

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

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

Schema description coverage is 0%, so the Args section must compensate. It does so effectively: item_id is described as the custom item ID to delete, while athlete_id and api_key are explained as optional with .env fallback. This adds meaningful context beyond the bare schema, especially the default behavior.

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: 'Delete a custom item for an athlete from Intervals.icu.' This clearly distinguishes it from siblings like delete_event, get_custom_item_by_id, create_custom_item, and update_custom_item. The agent can identify the tool's exact purpose 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?

No guidance is given on when to use this tool versus alternatives such as delete_event or update_custom_item. There are no prerequisites, no exclusions, and no mention of when deletion is appropriate or not. The description only states what the tool does, not when to select 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, the description carries the full burden of behavioral disclosure. It only states the deletion action and parameter fallback behavior, but does not disclose irreversibility, side effects, authorization requirements, error behavior, or what the response contains.

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

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

The description is compact and well-structured: a one-sentence purpose followed by a terse Args block. Each line earns its place and there is no filler.

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

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

This is a simple three-parameter delete operation with an output schema present, so the action and parameter list are largely sufficient. However, it lacks explicit differentiation from delete_events_by_date_range and does not provide behavioral caveats such as permanence or failure behavior, making it 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 0%, and the description compensates by documenting all three parameters. It adds useful semantics, especially the .env fallback for athlete_id and api_key and the required nature of event_id, though it does not elaborate on ID formats or constraints.

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 clear verb and resource: 'Delete event for an athlete from Intervals.icu.' It implies deleting a single event by event_id, which distinguishes it from sibling delete_events_by_date_range, but it does not explicitly name or contrast that alternative.

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

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

No when-to-use or when-not-to-use guidance is provided. The description does not mention that this tool is for deleting a single event versus using delete_events_by_date_range for bulk deletion, nor does it state any 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly states that this is a delete operation, but it does not mention whether deletion is permanent/irreversible, whether all events in the range are affected, whether any confirmation is required, or what side effects may occur. For a destructive bulk operation, 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 front-loaded with a clear one-sentence purpose, followed by a compact Args list. Every line provides useful information and there is no fluff, repetition, or irrelevant 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?

An output schema exists, so return-value documentation is not required. However, for a destructive tool with no annotations, the description omits important operational context such as irreversibility, range inclusivity, and potential impact on related data. The parameter documentation is strong, but the behavioral context is incomplete for safe 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 description coverage is 0%, but the description compensates well by documenting all four parameters. It explains that athlete_id and api_key are optional and fall back to .env values, and it specifies the YYYY-MM-DD format for start_date and end_date. It could add date-range boundary semantics (inclusive/exclusive) but otherwise adds substantial meaning beyond the schema.

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

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

The description states a specific verb ('Delete'), a resource ('events for an athlete from Intervals.icu'), and a clear scope ('in the specified date range'). This also distinguishes it from the sibling delete_event, which addresses a single event rather than a date-range bulk deletion.

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 usage context is implied by the name and description: use this tool when deleting multiple events by date range. However, it does not explicitly contrast it with alternatives like delete_event or explain when one should be preferred over the other, so 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 burden. It discloses meaningful behavior: date range defaults, default limit, include_unnamed behavior, and fallback to .env credentials. It does not cover error handling, ordering, or pagination, but the key operational defaults and auth fallback are well documented.

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 economically structured: a one-sentence purpose summary followed by a clean Args list. Each line adds concrete information about requiredness, defaults, or formatting, with no redundant or filler 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 6-parameter tool with no annotations and 0% schema description coverage, the description covers almost everything an agent needs: defaults, auth fallback, date format, and the include_unnamed flag. It does not mention ordering or constraints like start_date before end_date, but the presence of an output schema mitigates the need to describe return 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?

Schema description coverage is 0%, so the description must explain all parameters, and it does. Every parameter is listed with type, optionality, default, and additional meaning—including the .env fallback for athlete_id and api_key, and the YYYY-MM-DD format for dates. This fully compensates for the sparse 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 ('Get a list of activities') on a specific resource ('for an athlete from Intervals.icu'), which clearly distinguishes it from sibling tools like get_activity_details or get_activity_raw. The one-line summary plus parameter list makes the tool's purpose immediately understandable.

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 clear context on defaults and optional parameters, showing how the tool is typically invoked. However, it does not explicitly state when to use this tool versus a sibling such as get_activity_details or get_activity_intervals, so usage guidance relies on inference from the tool name and summary.

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 communicates that this is a read-style operation and provides auth context by noting the API key is optional and falls back to API_KEY from .env. However, it does not disclose output shape, error behavior, rate limits, or what 'detailed information' concretely includes.

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 core action, and uses a clean Args block for parameter details. Every sentence earns its place without redundant exposition.

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 fetch-by-ID tool, the description covers the operation, the service source, both parameters, and the auth fallback behavior. The existence of an output schema partially accounts for the lack of return-value documentation. Its main gap is not explaining when this tool should be selected over competing activity-fetching siblings.

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 no parameter descriptions, and the context notes 0% schema coverage, so the description must compensate. It does so clearly: activity_id is defined as 'The Intervals.icu activity ID', and api_key is explained as optional with an env fallback. This gives an agent enough semantic grounding to invoke the tool.

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 ('Get') and the resource ('detailed information for a specific activity from Intervals.icu'), making the tool's basic purpose understandable. However, it does not differentiate it from sibling tools like get_activity_raw, get_activity_intervals, or get_activity_streams, so an agent may still be unsure which activity-related fetch tool to choose.

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 the many sibling tools that also fetch activity data. The description only defines what the tool does and its parameters; it does not state prerequisites, exclusions, or alternatives. An agent is left to infer 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 provided, the description carries the behavioral disclosure burden. It discloses what the endpoint returns (power, heart rate, cadence, speed, environmental data, grouped intervals) and the API-key fallback behavior, which is useful for correct invocation. It does not cover rate limits or error behavior, but these are less critical for a read-only retrieval 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 compact and front-loaded with the primary purpose, then gives return details and parameter guidance without repetition. Every sentence contributes meaningful invocation 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 two-parameter retrieval tool with an output schema, the description covers purpose, parameter meaning, auth behavior, and the shape of returned data. It could be slightly more complete by stating explicit usage boundaries versus sibling activity endpoints, but nothing critical is missing for invoking it correctly.

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

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

Input schema has 0% description coverage, but the Args section documents both parameters: activity_id is identified as the Intervals.icu activity ID and api_key is explained as optional with a .env fallback. This fully compensates for the empty schema property 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 opening sentence names a specific action ('Get') and a distinct resource ('interval data for a specific activity'), which separates it from sibling tools like get_activity_streams or get_activity_raw. The following sentence reinforces the scope by listing the interval-level metrics returned.

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 conveys that the tool is for retrieving interval-level metrics and grouped intervals, so an agent can infer appropriate use. However, it does not explicitly state when to prefer this over alternatives or mention exclusions, leaving selection mostly to inference.

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

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

With no annotations provided, the description carries the transparency burden. It conveys a read-only 'Get' operation and explains API key fallback behavior, which is useful. However, it does not disclose error behavior, rate limits, or what happens if the activity_id is invalid.

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 concise and well-structured, with a clear first sentence followed by an Args list. Minor redundancy like repeating 'Intervals.icu' in both the summary and arg explanations does not significantly harm readability.

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 low parameter count, no nested objects, and the presence of an output schema, the description covers the essential invocation details: required ID and auth handling. It lacks explicit alternative routing and error-condition context, but is otherwise sufficient for a simple read 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 0%, so the description must compensate, and it does. It explains that activity_id is the Intervals.icu activity ID and that api_key is optional, falling back to API_KEY from .env. This adds meaningful semantic context beyond the bare 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 clearly states the verb 'Get' and the resource 'messages (notes/comments) for a specific activity.' It effectively differentiates from siblings like get_activity_details or get_activity_raw by specifying the message resource, though it does not explicitly name alternative 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 implies when to use the tool: when you need messages/comments for a specific activity. However, it provides no explicit guidance on when not to use it or which sibling alternatives (e.g., add_activity_message, get_activity_details) would be more appropriate for related needs.

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 behavioral disclosure burden. It clearly discloses that the tool returns raw, unmodified JSON and is temporary in nature, and it explains the API key fallback to .env. It does not explicitly state that the tool has no write side effects, but the 'get' + raw-return framing makes this a minor gap.

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

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

The description is front-loaded with a diagnostic label, followed by a concise behavior statement and a short usage context. The Args section is compact and every sentence earns its place without unnecessary verbosity.

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 that an output schema exists, the return value does not need to be described further. The description covers the tool's purpose, when to use it, its temporary lifespan, both parameters, and its relationship to the affected siblings, leaving no essential gap.

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

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

Schema description coverage is 0%, and the description fully compensates by explaining activity_id as the Intervals.icu activity ID and api_key as optional with a clear fallback to API_KEY from .env. This adds meaning well beyond the bare schema titles and types.

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 'DIAGNOSTIC TOOL (temporary)' and states the exact action: 'return the raw JSON the Intervals.icu API sends back for one activity, unmodified.' It explicitly names get_activity_details/get_activities as the tools whose blank-field behavior it diagnoses, clearly distinguishing it from 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?

It gives an explicit use case: debug why get_activity_details/get_activities show blank fields due to a field-name mismatch. It also says 'Safe to remove once the mapping bug is confirmed fixed,' which communicates that this is not a general-purpose tool and should only be used for that investigation.

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 transparency burden and does a solid job: it discloses that api_key is optional and falls back to API_KEY from .env, that stream_types defaults to all available types, and that the endpoint returns time-series data across many metrics. It does not discuss errors or rate limits, but the output schema reduces the need for detailed return-value explanation.

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 well structured with a concise summary followed by an Args list. The first sentence is mildly redundant with the rest of the summary, but the included metric enumeration and parameter explanations earn their 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?

All three parameters are documented with defaults and options, and an output schema is present, covering return-value expectations. The main missing context is explicit routing among sibling activity tools and failure/error behavior, but for a read-only stream retrieval tool this 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 description coverage is 0%, so the description must compensate, and it does thoroughly. It explains activity_id, api_key's optionality and .env fallback, and stream_types' comma-separated format, default behavior, and the full list of available stream types. This is exactly the parameter-level detail the schema omits.

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 and resource: 'Get stream data for a specific activity from Intervals.icu' and clarifies that it returns time-series metrics. It clearly identifies the tool's purpose, though it does not explicitly differentiate it from siblings like get_activity_raw or get_activity_intervals.

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 the intended use case: retrieving time-series stream data for an activity. However, it provides no explicit guidance about when to prefer this tool over alternatives such as get_activity_raw or get_activity_details, leaving an agent to infer the distinction from 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 provided, the description carries the behavioral disclosure burden. It usefully adds that the tool uses FFT power computation, reports values in watts, and returns best power for selected durations. It does not discuss authentication, rate limits, or side effects, but 'Get' and the stated purpose strongly imply a read-only 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?

The description is well structured: a one-sentence purpose, a concise behavioral note, and an Args block. It is front-loaded with the key facts and every sentence adds useful information without unnecessary fluff.

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

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

For a 10-parameter tool with no annotations and an output schema, the description is mostly complete: it explains purpose, computation method, units, and most parameters. The main gaps are the undocumented include_normalised parameter and lack of explicit guidance on auth/athlete identification, but overall an agent can call this tool effectively from the description.

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

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

Schema description coverage is 0%, so the description must compensate. It documents most parameters with helpful details: defaults, example values, allowed location filters, date format, and the mutual requirement between start_date and end_date. However, it omits explicit descriptions of include_normalised, athlete_id, and api_key, though those are largely inferable from their names.

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 ('power curves for an athlete from Intervals.icu'), and clearly states the output: best power output for selected durations across specified time periods. This distinguishes it from sibling tools like get_activities or get_activity_raw 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?

The description makes the tool's context clear: it is for retrieving power-curve data for an athlete, not for activity lists or raw streams. It does not explicitly name alternatives or state when not to use it, but the purpose is concrete enough that an agent can infer appropriate use.

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 burden of behavior disclosure. 'Get' implies a read-only operation, and the Args section usefully explains that athlete_id and api_key fall back to environment variables. However, it does not explicitly state side-effect safety, error behavior, or any API-specific constraints.

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 concise and front-loaded: a clear one-line purpose is followed by a compact Args list. No filler or redundant content is present, and every sentence contributes 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 operation with an output schema, the description is sufficiently complete. It identifies the source system, required and optional parameters, and the auth fallback strategy. Since an output schema exists, not explaining return values is acceptable.

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

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

Schema description coverage is 0%, but the description compensates by documenting all three parameters: item_id as the target ID, and athlete_id/api_key as optional credentials with explicit .env fallback behavior. This adds meaning beyond the raw schema by clarifying default resolution and optionality.

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 'Get', the resource ('detailed information for a specific custom item'), and the source system ('Intervals.icu'). The singular 'specific' distinguishes it from the sibling get_custom_items, which is best interpreted as a list operation.

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 is provided about when to use this tool instead of alternatives such as get_custom_items, get_activity_details, or get_event_by_id. The only selection hint is the phrase 'specific custom item' plus the tool name itself, which leaves usage context 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 behavioral transparency burden. It does disclose that both parameters are optional and fall back to environment variables, which is useful. However, it does not mention response shape, whether a list is always returned, pagination, possible auth failures, or other runtime behavior. The read-only 'Get' verb is present but not explicitly framed as a safe 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?

The description is concise and well-structured: a single front-loaded purpose sentence followed by an Args block. No fluff or irrelevant detail. Every sentence serves a functional role, and the structure makes parameter behavior easy to scan.

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-oriented nature of the tool and the presence of an output schema, the description covers the main invocation contract: what is retrieved, for whom, and how authentication is handled. The main missing piece is explicit routing to/from sibling tools, especially get_custom_item_by_id, and any caveats about empty results or auth errors. Overall it is close to complete for a straightforward list endpoint.

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

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

Schema description coverage is 0%, so the description must compensate. It clearly explains both parameters: athlete_id is the Intervals.icu athlete ID and api_key is the API key, and it notes that each falls back to a .env variable if omitted. This adds meaningful semantics beyond the bare schema and gives the agent enough to invoke the tool correctly.

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: 'Get custom items' with examples (charts, custom fields, zones) and the athlete scope. It doesn't explicitly distinguish from the sibling get_custom_item_by_id, but the plural 'items' and 'etc.' communicate a broader retrieval intent. This is more than a tautology and gives an agent a concrete sense of 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?

No guidance is given about when to prefer this tool over alternatives such as get_custom_item_by_id, create_custom_item, or update_custom_item. The description explains argument fallbacks but does not provide any when-to-use or when-not-to-use context. The agent is left to infer use cases 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 burden. It usefully discloses that athlete_id and api_key fall back to .env values, and 'Get' implies a read operation, but it does not describe not-found behavior, error cases, or confirm that no modifications occur.

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

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

The first sentence is a clear, front-loaded summary, and the Args block is organized without fluff. It is slightly redundant with the schema but each line adds some value, especially the environment-variable fallback notes.

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 with an output schema, the key call parameters are covered. However, the absence of usage differentiation and behavioral caveats (e.g., 404/error handling) leaves the description slightly incomplete for an agent choosing among many sibling tools.

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

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

Schema description coverage is 0%, and the description compensates for all three parameters: event_id is identified as the Intervals.icu event ID, while athlete_id and api_key receive meaningful optionality and .env fallback semantics not present in the schema.

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

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

The opening sentence specifies the verb ('Get'), the resource ('event'), and the scope ('specific event') from Intervals.icu. It distinguishes from list-like siblings such as get_events, but it does not explicitly name an alternative or contrast itself.

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 prefer this tool over get_events or other event tools, and no mention that the caller must already have an event_id. The usage context is only implied by the word 'specific'.

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 does reveal useful behavior: optional athlete_id and api_key fall back to .env values, and dates default to today and 30 days out. However, it does not mention read-only semantics, error cases when credentials are missing, pagination, or any external API call 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 compact and well-structured: a one-sentence purpose line followed by a brief Args block. Every line adds useful information, and there is no redundant fluff.

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

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

For a simple read tool with an output schema present and all parameters documented, the description is nearly complete. The main missing piece is guidance about how it relates to get_event_by_id and whether it returns all events or only filtered ones beyond the date range. Still, an agent can invoke it correctly using the provided parameter 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 0%, but the description fully compensates by documenting all four parameters with format, optionality, and defaults: athlete_id, api_key, start_date, end_date. It explains the YYYY-MM-DD format and the .env fallback behavior, adding meaning well beyond the bare schema types and null defaults.

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 what the tool does: 'Get events for an athlete from Intervals.icu'. It is an explicit verb plus resource and source. However, it does not explicitly distinguish itself from get_event_by_id or other event-related siblings, so it falls just short of the strongest possible clarity.

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 parameter-level usage details like date defaults and .env fallbacks, but it gives no guidance on when to choose this tool over get_event_by_id, add_or_update_event, or delete_event. There is no when-to-use or when-not-to-use context beyond the implied purpose.

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 results are cached for the MCP process lifetime, that refresh=True bypasses the cache, and that credentials fall back to environment variables. It also describes the return format. It does not discuss rate limits, errors, or pagination, but for a simple read-only catalog fetch the provided transparency is solid.

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 with the core purpose and return shape, then gives a compact, well-organized Args section. Every sentence adds actionable information: what is fetched, what the output looks like, how caching works, and how parameters behave. No filler or redundant restatement of the tool name is present.

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 tool with a provided output schema, the description is complete. It explains the data source, return granularity, caching semantics, authentication fallbacks, and refresh override. An agent has enough information to invoke the tool correctly without additional documentation.

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

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

Schema description coverage is 0%, so the description must explain the parameters, and it does so thoroughly. athlete_id, api_key, and refresh each receive a plain-language explanation including optionality, environment-variable fallback, and default behavior. This fully compensates for the schema's lack of descriptive text.

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: 'Get the gear catalog (bikes, shoes, etc.) for an athlete from Intervals.icu.' It also clarifies the output shape ('one line per gear item with id, type, name, and basic stats'), making the tool's purpose unmistakable. No sibling tool focuses on gear catalog, so it is effectively distinguished from the provided 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 clear context: this is the gear-list retrieval endpoint for an athlete, with caching behavior and optional authentication via environment variables. It does not explicitly exclude alternatives or provide when-to-use versus when-not-to-use guidance, but the purpose is specific enough that an agent can infer when to call it. There are no misleading usage signals.

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. It does so well by revealing that standard fields are returned by default, that include_all_fields=True extends to custom fields, that athlete_id and api_key optionally fall back to .env values, and that dates default to a 30-day window. It does not mention error behavior or rate limits, but it adequately describes what the tool does at invocation time.

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 moderately sized and well-structured: a purpose sentence, a sentence about behaviors, and a logical Args block. The Args lines repeat parameter names from the schema but add valuable default and format context, so nothing is wasted. It could be slightly tighter, but it remains readable and front-loaded with the core function.

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 five all-optional parameters and an existing output schema, the description supplies enough to call the tool correctly: parameter defaults, credential sources, date formats, and the field-scoping flag. There is no need to describe return values because the output schema exists. Minor omissions like invalid-input handling do not impede 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 0%, so the description is the sole source of param meaning. It fully compensates by documenting all five parameters in the Args section, adding format specifics (YYYY-MM-DD), default values (30 days ago, today, False), and the .env fallback for credentials. This is exactly the semantics an agent needs beyond raw JSON 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 and resource: 'Get wellness data for an athlete from Intervals.icu.' It then enumerates the content domains (training metrics, vitals, sleep, subjective scores), which clearly separates it from sibling tools focused on activities, events, gear, and custom items. There is no ambiguity about 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 establishes a clear use context: whenever an agent needs wellness data for an athlete. It also gives practical guidance on the include_all_fields flag, explaining when to set it to True. It does not explicitly name alternative tools or state when not to use it, but the semantics of 'wellness data' are distinct enough among the siblings to provide clear direction.

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 optional auth defaults from .env and important enum constraints for content fields, but does not state whether the update is partial or full replacement, what happens to unspecified fields, or what the response indicates. This is partial transparency.

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 purpose statement is front-loaded, followed by a structured Args list. The content is detailed but not redundant, though it could trim some obvious parameter names; overall it is well organized and every sentence adds 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?

Given 8 parameters, no schema descriptions, and no annotations, the description covers all parameters and key constraints. It omits explicit update semantics but the presence of an output schema reduces the need to document return values, so this 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 description coverage is 0%, so the description must compensate, and it does. It explains the meaning of all 8 parameters, including the item_id, optional athlete_id/api_key fallback behavior, and the required enum values for content.type and content.aggregate, adding value beyond the bare 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 starts with a specific action and resource: 'Update an existing custom item for an athlete on Intervals.icu.' This clearly distinguishes it from sibling tools like create_custom_item, delete_custom_item, and get_custom_item_by_id.

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 through the verb 'Update' and lists optional fields, but it does not explicitly state when to prefer this over create_custom_item or delete_custom_item, nor mention any preconditions such as the item needing to exist.

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