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

With no annotations, the description carries the full burden; 'analytics' and 'DataMart aggregation' imply a read-only, non-REST-backed query, and the 'merged with componentType: project' behavior is disclosed via schema. It does not state result ordering, how truncation at limit behaves, or any caveats about summing budget across groups — meaningful gaps for a metrics tool.

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

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

Three tight sentences: capability first, provenance second, valid inputs third. Every clause carries information an agent needs 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?

For a 2-required-parameter analytics tool with no annotations and no output schema, the description never hints at the result shape (group key plus metric values) or ordering, leaving the agent to guess what comes back. It does cover the input side well and flags the DataMart provenance.

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 baseline is 3, but the description adds genuine value by enumerating the actual valid groupBy field paths (statusLabel, priorityLabel, methodology, customTypeLabel, isClosed, managers.name) where the schema only offers 'e.g.' examples. The metrics values and limit defaults are already fully documented in the schema, so nothing further is added there.

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 (aggregate/compute) and resource (portfolio-level project data) with the exact metrics available, which is far more informative than the bare name. However it never names a sibling such as query_datamart or search_projects to make the boundary explicit — an agent must infer which aggregation entry point is correct.

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 enumerated groupBy fields and the note 'no REST equivalent' implicitly tell the agent this is the DataMart path for grouped rollups rather than per-entity lookups. There is no explicit 'use this instead of X' or 'not for single-project totals' guidance, so the routing decision is left 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, the description still discloses important behavioral traits: the 100-ID chunk limit, the failed-array inspection requirement, safe retry semantics for failed chunks, and the activity-status versus task-status distinction. It does not explicitly discuss permissions, whether the update is reversible, or the full response shape, so it falls short of fully carrying the behavioral burden 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?

Three tightly packed sentences front-load the operation, then give prerequisites, limits, and failure handling. Every sentence contributes actionable guidance with no repetition 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 bulk mutation with no annotations and no output schema, the description covers the essential workflow, the 100-item limit, status resolution, and failed-array handling. It stops short of describing the full return payload or permission requirements, but it provides enough to call the tool correctly and safely retry failed chunks.

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 five parameters and the statusId/statusName alternative. The description adds meaningful context beyond the schema by naming the reference-data entity for activity statuses and distinguishing them from task statuses, though it does not elaborate on projectMethodTypeId or serviceId semantics beyond what the schema provides.

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

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

The description opens with a specific verb and resource: "Apply one status to many activities of a service in a single call." It clearly distinguishes a bulk activity-status mutation from singular update_activity and from task-status operations elsewhere. An agent can identify the operation 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?

It explicitly prescribes the workflow: collect activity IDs via list_service_activities, chunk into calls of at most 100 IDs, and resolve status IDs via get_reference_data with entity "activitystatuses" or pass statusName. It also warns that activity statuses differ from task statuses and directs the agent to check the failed array, including that retrying a failed chunk is safe.

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 and adds real context: 100-ID chunking, Waterfall vs Kanban status semantics, and retry safety for failed chunks. It stops short of stating whether the call is atomic or what a fully successful response looks like, which leaves a small 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?

Front-loaded with the core action, then chunking, then status resolution, then failure handling – a sensible order with no filler. The middle sentence is dense and packs several distinct rules into one clause chain, which slightly hurts scannability.

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 must cover behavior, and it largely does – preconditions, input sourcing, batching limits, and the failed-array check. What is missing is the success-path return shape and any permission requirements, which matters for a bulk mutation.

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 baseline is 3, but the description adds cross-parameter logic the schema only hints at: statusId vs statusName as an either/or, and why projectMethodTypeId is required for Kanban resolution. The 1/2 enum mapping is repeated from the schema, so not all of it is new 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?

Opens with a specific verb+resource+scope: one status applied to many tasks of a project in a single call. Explicitly contrasts with the sibling update_task ('faster than looping update_task'), so the agent can route correctly without opening 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?

Names the siblings that supply inputs (list_project_tasks, search_tasks, get_reference_data) and the exact entity name to resolve statuses. It states the alternative (loop update_task) and the conditions that make this tool preferable, plus the chunking rule.

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. It usefully discloses that the resource is flat (no milestones/hierarchy) and which fields are mandatory, but says nothing about permissions, whether the created activity is returned, duplicate/validation behavior, or any rate limits.

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

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

Three tight sentences, front-loaded with the action and the most surprising constraint (flat list), then requirements, then the status-ID prerequisite. No filler to cut.

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

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

For an 11-parameter mutation with no output schema, the description covers required fields, the notable unsupported-shape trap, and the status-ID discovery path. It is nearly complete, missing only return-value expectations and failure/permission 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 100%, so each parameter including the 'NOT SUPPORTED' KindId/ParentId notes is already documented in the schema. The description largely restates required-field and status-lookup facts the schema already encodes, adding little new syntax or format detail.

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

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

States a specific verb and resource ('Create a new activity in a service') and immediately scopes it by noting activities are a flat list with no hierarchy. It implies but never explicitly states the distinction from the sibling create_task, which is the main confusion risk.

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

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

Gives concrete prerequisite guidance: activity statuses differ from task statuses and valid IDs must be discovered via get_reference_data with entity "activitystatuses". It does not state when an agent should choose create_activity over create_task/create_project, so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full burden, and it does disclose one useful behavior, that localized IDs are normalized automatically. It does not state permission requirements, whether required-field validation is enforced server-side, or what the tool returns, leaving significant gaps for a mutation 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?

Two short sentences, front-loaded with the action and followed by the setup step; nothing is repeated or 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?

The creation action and the ID-discovery path are covered, and the full input schema is available. Without an output schema, though, the description says nothing about what a successful call returns or how failures surface, which matters for a write tool with no annotations.

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

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

Schema coverage is 100%, so all six parameters are self-documented, which sets the baseline at 3. The description adds moderate value by pointing the agent to reference-data entities for the StatusId and TypeId values it must supply.

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, stating it will 'Log a new issue in a project.' That clearly separates it from get_issue, get_project_issues and update_issue among the siblings, though it never names those siblings explicitly.

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

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

It gives a concrete prerequisite, telling the agent to fetch issuestatuses and issuetypes via get_reference_data before calling. However, it does not say when to use this versus update_issue, or what conditions should block creation such as missing project or duplicate issues.

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 and does real work: it discloses defaults (Waterfall when ProjectMethodTypeId is omitted, account default status), side effects (Kanban gets default board columns), and a permission-dependent consequence (the caller becomes project manager when their license allows). It does not describe the return payload or failure behavior (e.g., what happens on a non-unique name), which is the remaining gap for an unannotated 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?

Four dense sentences, front-loaded with required fields, then the methodology mapping, then the creation constraint and its workaround. No filler and every clause carries information an agent needs before calling.

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, unannotated, output-schema-less create tool, the description covers defaults, permission side effects, and the status constraint well. It leaves the agent guessing about the response (does it return the new project ID?) and any creation failure modes, which matters when there is no output schema to fall back on.

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 meaning beyond the schema by explaining that ProjectMethodTypeId=2 creates Kanban with default board columns and that status parameters are inert at creation. These are consequences of parameter choice, not restatements of the field docs.

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 ('Create a new project') and immediately names the required fields. It also names the sibling used for the one thing this tool cannot do ('change it with update_project'), so the agent can separate creation from mutation without opening 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?

It gives clear preconditions (Name and TypeId required), the entity to look up for TypeId, and an explicit boundary: StatusId/ProjectStatusId cannot be set here, use update_project instead. It stops short of stating when not to create (e.g., duplicate-name handling) or pointing at search_projects as a pre-check, so it is clear but not exhaustive.

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 and does well: it discloses the critical side effect that percentage 100 automatically CLOSES the project and blocks further time entry, plus the recovery path via update_project. It does not cover permission/auth requirements or behavior on duplicate report dates for the same project.

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

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

Front-loads the core action, then the independence note, then the destructive-side-effect warning, then the lookup hint. No filler sentences; the WARNING casing makes the highest-risk fact scannable.

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 mutation tool with no annotations and no output schema, the description covers the essential gotcha, the reference-data lookup, and the sibling boundary. It leaves open whether the call returns the new entry ID and how repeat reports for the same date are handled.

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 baseline is 3, but the description adds meaning beyond the schema: the consequence of percentage=100 (project closure), and the source of valid assessmentId values. It adds little about shortDescription vs. description 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?

Names a specific verb and resource ('Create a project-level progress (Seguimiento) entry') and enumerates the payload fields (report date, completion percentage, assessment rating, status description). It explicitly distinguishes itself from the per-task variant by stating it is 'Independent from per-task progress', separating it from siblings like create_task_progress.

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

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

Gives concrete pre-conditions ('log hours first' before setting 100%) and points to get_reference_data for assessment IDs and update_project for reopening. It implies rather than explicitly names create_task_progress as the alternative for task-level reporting, so the routing is slightly less than complete.

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 behavioral burden. It usefully discloses that localized Ids are normalized automatically, but it does not describe permissions, mutation side effects, error behavior, or what a successful call 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?

Three sentences, front-loaded with the core action, followed by required-field guidance and a discovery hint. There is no filler, and each sentence contributes actionable 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 create tool with full schema descriptions, the definition covers the key invocation prerequisites and ID discovery. It is mostly complete, though without an output schema it could say more about the return value or post-create 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 already 100%, so the baseline is 3. The description adds some semantic value by reiterating required ID parameters, mapping them to reference-data entities, and noting automatic normalization of localized Ids.

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: 'Log a new risk in a project.' This clearly distinguishes creation from sibling update_risk and get_project_risks, although it does not explicitly name those siblings as 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?

It gives clear prerequisite guidance: TypeId, StatusId, ImpactId, ProbabilityId, and LevelId are required and should be discovered via get_reference_data with named entities. It does not explicitly say when to use update_risk instead, but creation is sufficiently implied.

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 burden and does disclose a non-obvious behavior: the service is always created with the account default status and status cannot be set at creation. It doesn't cover failure modes (e.g., duplicate name rejection) or what is returned, which a mutation tool would ideally mention.

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

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

Three short sentences, front-loaded with the action, then requirements, then the status caveat. Every sentence adds information an agent needs.

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

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

A 9-parameter create tool with no annotations and no output schema needs the required-field and status constraints, and the description supplies both plus the type-lookup path. The main gap is that nothing tells the agent what the response contains (e.g., new service ID) or what to chain next.

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 baseline is 3; the description adds value by restating the two required fields and pointing at the exact reference-data lookup for TypeId. That cross-parameter workflow hint is not 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?

States a specific verb and resource ('Create a new service') and immediately separates the creation step from the follow-up mutation by naming update_service. An agent can distinguish it from update_service and search_services without inspecting any schema.

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

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

Gives concrete routing: use get_reference_data with entity "servicetypes" to obtain a valid TypeId, and use update_service when a non-default status is needed. It stops short of saying when to create versus not create (e.g., duplicates), but the operational guidance 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 disclosure burden and does well: it states Waterfall/Kanban support boundaries, required fields by kind, Kanban board-default behavior, ParentId hierarchy effects, and AutomaticProgress behavior. It stops short of describing permissions, side effects on existing parent tasks, or failure modes.

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

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

The description is dense but well front-loaded, opening with the core action and then layering the conditional rules that matter most. Every sentence conveys creation constraints or semantics; there is little wasted text despite the complexity.

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 13-parameter create tool with no annotations and no output schema, the description covers the key domain rules an agent needs to invoke it correctly. It could be stronger by mentioning the return shape or permission requirements, but the essential creation semantics are present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-field meaning: KindId values and the KindId/TypeId distinction, Waterfall vs. Kanban requirements for StatusId and dates, and ParentId hierarchy behavior. It still leaves several parameters such as TaskMembers, TaskManagers, and PriorityId to the schema.

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

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

Starts with a specific verb and resource: 'Create a regular task, milestone, or summary task.' It immediately distinguishes the supported task kinds and clarifies KindId vs TypeId, so an agent can tell this apart from update_task or create_task_progress 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?

Gives clear conditional usage by waterfall vs. Kanban and by task kind, including required fields for each case. It does not explicitly name alternatives such as update_task or create_task_progress, but the creation context is strong and 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?

With no annotations, the description carries the behavioral burden and does well: it discloses that creating progress triggers status transitions, parent task rollups, project progress recalculation, events, and notifications. It does not cover permissions, validation failures, or whether the created entry can later be edited or deleted, so it is strong but not complete.

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, front-loaded with the purpose, followed by consequential behavior and the assessment lookup hint. There is no wasted text, and the most important side effects are 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?

For a mutation tool with no annotations and no output schema, the description is reasonably complete: it explains purpose, key side effects, and required assessment lookup. It could further explain permissions, error behavior, or what the created entry returns, but the schema covers parameters well.

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 seven parameters are already documented in the schema. The description only repeats the assessmentId discovery hint and adds no new parameter-level meaning beyond that 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 states a specific verb and resource: reporting progress by creating a new task progress/follow-up entry. It clearly explains this is the way to set completion percentage, but it does not explicitly name or compare against the sibling update_task_progress, leaving some ambiguity about why to create rather than update an existing progress entry.

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

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

It gives clear usage context by saying this is the correct way to set a task's completion percentage and by pointing to get_reference_data for assessmentId discovery. It does not state when not to use it or explicitly name alternatives such as update_task_progress or bulk_update_task_status.

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 and does so well by implying a read-only lookup, specifying supported field types, listing returned fields, and explaining that option Text is the value stored in DataMart customFields. It does not discuss permissions, error behavior, or pagination, but for a simple lookup the key behavioral context is present.

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 action, then lists supported types and return fields compactly. Every sentence adds useful information without waste.

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 there is no output schema, the description explicitly lists the return fields and explains the important DataMart customFields semantic. Together with the fully documented input schema, this gives the agent enough context 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?

Schema description coverage is 100%, so both parameters are already documented in the schema. The description reinforces that customFieldBaseId must come from get_custom_fields, but it adds limited additional parameter semantics 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 and resource: get the selectable options of a dropdown custom field. It names the supported field types (RYGList, DropDownList, List) and distinguishes this from get_custom_fields by requiring the BaseId returned there.

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 clearly establishes the prerequisite that the BaseId comes from get_custom_fields, so the agent knows this tool is used after retrieving custom fields. It does not explicitly state when not to use it or name alternatives, but the context is strong for this narrow lookup 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?

With no annotations, the description carries the burden and does well: it enumerates the returned fields, warns that DataMart keys are case- and accent-sensitive and may carry trailing spaces, and explains multilingual keying per languageId. It omits permissions/pagination/refresh behavior, but for a read-only definition lookup this is substantial 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?

Front-loads the purpose, then return shape, then the non-obvious DataMart key semantics, then sibling routing — a sensible information order. Slight redundancy in re-listing the eight entity types already encoded in the enum, and the trailing-spaces warning is dense but 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?

There is no output schema, so the description compensates by listing the returned fields (Id, BaseId, Name, TypeId, TypeName, Description, Required). Combined with the DataMart key guidance and the sibling pointer, an agent has enough to call it and use the result correctly; only auth/pagination behavior is unstated.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning for languageId: on multilingual accounts key names follow each component's language and definitions must be fetched per languageId to map variants of the same BaseId. The entity list merely restates the enum and adds no new meaning.

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

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

States a specific verb (get) and resource (custom field definitions) plus the exact entity scope covered. It also distinguishes itself from the closely named sibling get_custom_field_options, so an agent can route without opening both 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?

Gives concrete downstream routing: query values via query_datamart with examples of the filter shape, and use get_custom_field_options for dropdown values. It lacks an explicit negative case (e.g. versus get_reference_data), but the positive guidance is unusually actionable.

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

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

With no annotations, the description carries the full burden. It does disclose the returned field set, the backend source, and the discovery prerequisite, and 'Get' implies a read-only operation, but it never states access requirements, error behavior for missing IDs, or explicitly confirms it is non-mutating.

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, front-loaded with the action and scope, then the returned payload, then the prerequisite. The field enumeration earns its place given there is no output schema.

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

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

No output schema exists, and the description compensates by enumerating the returned fields (type, status, manager, costs/hours, impact, resolution, custom fields). Combined with the ID-discovery prerequisite, an agent has enough to call it correctly; only error/permission behavior is absent.

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

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

Schema description coverage is 100%, so both projectId and issueId are already documented; baseline 3 applies. The description adds only the indirect hint that issueId comes from get_project_issues, with no added format or scoping detail.

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

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

States a specific verb and resource ('Get full detail of a single issue') and names the data source ('v2 REST (source of truth)'). The singular-single framing clearly distinguishes it from the sibling list tool get_project_issues and from the mutation siblings create_issue/update_issue.

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

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

Explicitly routes the agent: 'Use get_project_issues first to discover issue IDs,' establishing a prerequisite and a clear alternative for enumeration. It lacks an explicit exclusion (e.g. 'do not use for searching by text'), keeping it short of a 5.

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

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

With no annotations, the description carries the full burden; 'Get' implies a read-only operation and the note that subcomponent arrays are not returned is genuinely useful behavioral context. However, it says nothing about permissions, behavior when the projectId doesn't exist, or that include=budget triggers extra computation/cost.

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

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

Two sentences, zero filler, and the core behavior is front-loaded before the alternative-tool routing. Every clause carries information an agent needs.

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

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

For a two-parameter read tool with no output schema, the description gives enough to call it correctly and sets expectations about what is and isn't in the response. It could go slightly further by sketching the returned project fields, but the essentials are present.

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

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

Schema coverage is 100%, so the baseline is 3; both parameters are already documented in the schema, including the 'budget' enum and the note that subcomponents come from other tools. The description's 'include: ["budget"]' example restates rather than extends the schema.

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

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

States a specific verb and resource ('Get project details by ID') plus the distinguishing scope ('with subcomponent counts'), and names the dedicated sibling tools for each excluded subcomponent. An agent can tell it apart from list_project_tasks, get_project_risks, etc. without opening a schema.

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

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

Explicitly says when to use this tool (project details, and budget via include) and when not to (tasks, risks, issues, purchases, revenues go to named dedicated tools). The only gap is that it never points to search_projects for obtaining the projectId in the first place.

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 behavioral burden; 'Get' and 'Returns' imply a read-only call but nothing states it outright. The enumeration of the four returned objects is genuinely useful behavioral context absent an output schema, though permission or rate-limit behavior is unaddressed.

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

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

Two sentences, zero waste, with the action and the return payload front-loaded. Every clause earns its place by naming the four budget objects.

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

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

With no output schema, the description correctly compensates by naming the four budget objects and their meanings (planned/estimated/forecast/spent). It stops short of the behavioral context a zero-annotation mutation-free tool could still add, but nothing essential for calling it correctly is missing.

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

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

Schema description coverage is 100% for the single projectId parameter, so the schema already documents it, and the description adds no format or scoping detail beyond it. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Get budget summary for a project') and enumerates the four budget objects returned, which distinguishes it from sibling getters like get_project or get_project_progress. An agent knows exactly what this tool produces without opening a schema.

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

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

Usage is only implied by the resource name; the description never says when to prefer this over siblings such as get_project or query_datamart/aggregate_portfolio, nor any prerequisites. Adequate for a plainly named read getter but no explicit 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 burden and does disclose the return envelope ({ items, total, limit, skip, hasMore }) and the default/max page size, which is genuine behavioral context. It stops short of stating read-only semantics explicitly or any auth/failure behavior.

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

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

Two tight sentences; purpose first, then return shape and paging limits. 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?

No output schema exists, and the description compensates by naming the response envelope and its paging fields, which is the key missing piece for an agent. The remaining gap is sibling routing, not call correctness.

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 description's 'Default limit: 50, max: 200' merely restates what the limit parameter description already says. No added meaning for skip or projectId beyond the schema.

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

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

States a specific verb and resource ('Get issues for a project') with pagination scope, which is unambiguous on its own. However, it doesn't distinguish itself from siblings like get_issue (single issue) or search_tasks/get_project_risks, so the agent must infer the boundary.

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

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

No when-to-use or when-not-to-use guidance; the phrase 'with pagination' hints at large result sets but doesn't say to prefer get_issue for a single issue or search_* for filtered lookups. The agent gets no routing signal among the many sibling list/get 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, the description carries the burden and does so reasonably: it discloses the returned datasets, that entries are opt-in ('includeEntries true adds'), and that the default is false. It doesn't state access requirements or explicitly that the call is read-only, leaving a small 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?

Two tight sentences with the primary payload front-loaded and the optional flag handled second. Minor friction from the untranslated 'Seguimiento' and the clipped 'includeEntries true' phrasing.

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, so the description must convey return shape, and it does identify the three top-level results plus the entry fields. An agent knows enough to call it and to decide on includeEntries; pagination or size expectations are the only omission.

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 further by spelling out what the boolean actually unlocks (Seguimiento entries with ProjectProgressId, assessment, descriptions) — context the schema does not provide. projectId itself is only restated.

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 the project progress report') and enumerates the payload (expected curve, baseline curve, follow-up history). It is clearly distinguishable from the mutation siblings create_project_progress/update_project_progress, which it implicitly complements.

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

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

The clause 'for update_project_progress' ties the includeEntries option to a concrete downstream use, which is an effective when-to-use cue. It stops short of explicit exclusions or naming a sibling read alternative, so it isn't a full 5.

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

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

With no annotations, the description carries the full burden; 'Get' implies a safe read, and it usefully discloses the pagination defaults (50) and hard ceiling (200). It says nothing about permissions, error behavior for an invalid projectId, or ordering of results, which are the remaining behavioral gaps for an unannotated 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?

Two short sentences, front-loaded with purpose and immediately followed by the return shape and pagination contract. Every clause earns its place with no filler.

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

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

Since there is no output schema, the inline return shape { items, total, limit, skip, hasMore } is genuinely valuable and makes the tool callable without guessing at the response. Only sorting and failure modes are left unspecified, which are minor for a simple paginated list.

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 description mostly restates the limit defaults already documented in the schema. It adds no meaning about skip semantics beyond 'for pagination' or about what projectId must reference.

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 purchase orders') and scopes it to a project, which is more precise than the name alone. It does not distinguish itself from the very similar sibling get_service_purchases, so an agent comparing the two must infer the difference from the names.

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 statement of when to use this tool, when not to, or how it relates to get_service_purchases, get_project_budget, or get_project_revenues. The only implied guidance is 'for a project', which the schema's required projectId already conveys.

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 burden and mostly succeeds: it discloses pagination behavior, the default limit of 50, the hard max of 200, and the exact response envelope. It omits any statement about permissions or whether results are sorted/filtered, which are the remaining 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?

Two compact sentences; purpose is front-loaded and pagination constraints follow. Minor redundancy with the schema's limit description is the only waste.

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

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

With no output schema, the description supplies the return shape { items, total, limit, skip, hasMore }, and the three parameters are fully handled via schema. Enough to invoke correctly, though lacking guidance on the sibling revenue 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% and the schema already documents skip, limit (default 50, max 200), and projectId. The description merely restates the limit bounds rather than adding semantics such as default skip behavior or what happens when skip exceeds total.

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 revenue items for a project') plus pagination scope. The 'project' qualifier implicitly separates it from get_service_revenues in the sibling list, but the differentiation is never made explicit.

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

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

The read-retrieval context is implied by 'Get', but there is no statement of when to use this versus the closely-named sibling get_service_revenues, nor any preconditions 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 burden of behavioral disclosure. It usefully explains pagination defaults, maximums, and return shape, but does not cover permissions, ordering, or other read-operation traits.

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

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

Two sentences, front-loaded with purpose and pagination behavior. Every sentence adds information and 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?

No output schema exists, so the description helpfully includes the return object shape. For a simple read/list tool this is mostly complete, though it could mention ordering or what fields a risk contains.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description repeats the default limit and max, adding little beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Get risks for a project.' It is clear what the tool does, though it does not explicitly distinguish itself from siblings like get_risk or get_project_issues.

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 use this tool versus alternatives. It implies usage by saying 'for a project' but never names sibling tools or conditions for choosing between them.

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 behavioral burden. It usefully discloses that write tools accept either localized Id or BaseId and normalize as needed, but does not state that this tool is read-only/safe, describe the return shape, or note caching/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?

Two dense but efficient sentences, front-loaded with the core purpose followed by entity-selection guidance. The long enumeration is justified by the enum, though the slash-separated entity names are slightly harder 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?

For a single-parameter lookup with no output schema and no annotations, the description covers what entity to choose but leaves the return structure unspecified (e.g., whether it returns an array of IDs with names/BaseIds). Adequate for selection, but not fully complete for a tool whose output is consumed by write operations.

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

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

Schema coverage is 100% and the enum values are already listed, so the baseline is 3. The description adds real semantic value by mapping entity names to intended usage contexts (e.g., assessments for task progress, activitystatuses/servicetypes for service writes).

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 reference IDs' plus the categories of reference data covered. It is unmistakably a lookup tool and distinct from the CRUD/search siblings, though it does not explicitly contrast itself 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?

Provides explicit entity-selection guidance such as 'Use assessments for task progress' and 'riskstatuses... for risks.' It lacks explicit when-not-to-use guidance or named alternatives, but for a unique lookup tool this mapping is strong 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?

No annotations, so the description carries the burden, and it does well: it discloses the payload contents (mitigation and contingency plans, probability, impact, level, occurrence cost, manager) and flags that v2 REST is the authoritative source. It does not cover auth, rate limits, or behavior for missing/invalid risk IDs.

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

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

Two sentences, zero waste, with the identity of the resource front-loaded and the prerequisite instruction placed after it. Every clause 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?

There is no output schema, but the description compensates by enumerating the returned fields, so an agent knows what it gets. What's left out — error behavior for a bad riskId — is minor for a simple two-parameter read.

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 both parameters documented ('The risk ID', 'The project ID containing the risk'), so the schema already carries semantics. The description adds no format or constraint detail beyond implying riskId comes from get_project_risks, which is the baseline-3 case.

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

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

Names a specific verb and resource ('Get full detail of a single risk') and scopes it to the v2 REST source of truth, which distinguishes it from the list-style sibling get_project_risks. An agent can tell immediately whether this is the single-record fetch it needs.

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

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

Explicitly routes the agent: 'Use get_project_risks first to discover risk IDs,' naming the sibling and the prerequisite for a required parameter. It stops short of stating when NOT to call it (e.g., bulk retrieval), but the single-vs-list split 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 and does a good job: it discloses that subcomponent counts are returned, that budget data is opt-in, and that subcomponent arrays are not returned here but through dedicated tools. It does not explicitly discuss permissions or error behavior, but the read-only nature is strongly implied by '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 tightly written sentences with no waste. The core purpose and scoping constraints are front-loaded before the alternative-tool 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 two-parameter read tool with full schema coverage, the description is nearly complete: it says what details and counts are returned, how to include budget, and where subcomponent data lives. It does not enumerate return fields, but that is a minor gap given the tool's 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 description coverage is 100%, so the schema already defines serviceId and the include enum. The description reinforces the include behavior for budget but adds little beyond what the schema already documents.

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 service details by ID. It also specifies return scope (subcomponent counts) and distinguishes this tool from the dedicated activity, purchase, and revenue 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?

It clearly indicates when to use this tool (fetching one service by ID) and when to use alternatives for activities, purchases, and revenues. The optional budget inclusion condition is also stated 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?

No annotations are provided, so the description carries the full behavioral burden. It helpfully discloses the return shape ({ items, total, limit, skip, hasMore }) and the page-size ceiling, but says nothing about permissions, invalid serviceId behavior, or whether an empty result is an error.

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

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

Three short sentences with the purpose front-loaded, followed by return shape and limits – no filler. The limit defaults are repeated from the schema, a minor 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 three-parameter read tool with no output schema, the description compensates by declaring the exact response fields and pagination behavior. Only edge-case behavior (invalid serviceId, empty results) is left unspecified.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, and the description merely restates the default/max limit values. Baseline 3 applies since the schema does the heavy lifting and the description adds no new parameter semantics.

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

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

States a specific verb (Get) and resource (purchase orders) scoped to a service, which distinguishes it in substance from the sibling get_project_purchases. It does not name that sibling or otherwise explicitly differentiate, so it falls short of a 5.

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

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

There is no statement of when to use this tool versus get_project_purchases or any other sibling, and no prerequisites or exclusions are given. Usage is only inferable from the tool name and the 'for a service' scoping phrase.

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 and does reasonably well: it declares the return shape (items, total, limit, skip, hasMore) and the pagination defaults and ceiling. It omits mention of the empty-result case and permissions, but for a straightforward read tool this 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?

Two sentences, both front-loaded with the operation and then the payload/pagination contract. No filler and no repetition beyond the useful limit restatement.

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

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

No output schema exists, but the description supplies the response envelope, which is the key missing piece. Pagination and the required serviceId are covered; only edge cases like empty result sets are unaddressed.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema. The description's mention of default 50 / max 200 and the skip/limit pairing restates schema content rather than adding new meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get revenue items for a service') and scopes it to a service, which implicitly separates it from sibling get_project_revenues. It stops short of explicitly naming the sibling it is not, so it is clear but not fully differentiated.

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

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

The service scoping implies the usage context, but there is no explicit statement of when to use this versus get_project_revenues or search_services, nor any prerequisites or exclusions. Usage must be inferred from the resource name.

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

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

No annotations are provided, so the description carries the burden. It usefully discloses data freshness (bypasses DataMart sync delay) and enumerates the returned fields, but says nothing about failure modes for an unknown taskId/projectId, permission requirements, or read-only safety guarantees.

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, front-loaded with the action, then the payload, then the prerequisite. Nothing is redundant and every sentence contributes.

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

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

With no output schema, the description compensates by listing the returned field groups, and it establishes the authoritative-source detail an agent needs to trust the values. It stops short of covering error behavior or how projectId relates to taskId scope.

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 both taskId and projectId, so the baseline applies; the description only adds that task IDs come from list_project_tasks or search_tasks, which is helpful but marginal.

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

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

States a specific verb and resource (fetch full detail of one task) and adds a distinguishing scope claim — v2 REST as source of truth, unaffected by DataMart sync delay — which separates it from query_datamart and the list/search 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?

Explicitly routes the agent: use list_project_tasks or search_tasks first to obtain a task ID. That covers the prerequisite workflow well, though it doesn't state what to do instead when a cheaper summary would suffice or what the tool is not for.

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 and does disclose that this is a read returning estimates, accepted actuals, and worked time, plus that the response contains a teamMembers collection keyed by TaskUserId. It does not state permissions, scoping, or whether effort is aggregated across all assignees, so a small gap remains.

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

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

Three tight sentences, front-loaded with the return contents and ending with the sibling pointer. Slightly dense phrasing ('TaskUserId is the assignment key') assumes context the reader may not have, but nothing is wasted.

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

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

No output schema exists, so the description must describe returns, and it does name the three effort metrics plus the teamMembers/UserId/name/email structure. It leaves open whether results are per-assignee, per-category, or aggregated, which an agent would want to know before formatting its answer.

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 both taskId and projectId, so the schema already documents the inputs; the description adds no extra syntax or constraint information. Baseline 3 applies, though its explanation of TaskUserId as the response-side assignment key is a bonus covered elsewhere.

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 ('Read') and resource ('task effort') and enumerates the three quantities returned: planned estimates, accepted actual effort, worked time. It distinguishes itself from the write counterpart update_task_effort, though it doesn't differentiate against near neighbors like get_task or list_task_progress.

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 closing sentence implicitly gives a read-vs-write split: read here, write with update_task_effort. There is no explicit 'use this when...' guidance or exclusions versus other task inspection tools such as get_task or list_task_progress.

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 behavioral burden. 'Get' implies a safe read, and it usefully lists the return contents (roles, categories, contact info) since there is no output schema, but it says nothing about permissions, behavior when the ID does not exist, or errors.

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

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

Two short sentences, front-loaded with the core action and scope, with zero filler. Every clause 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 single-parameter read tool with no output schema, the description covers what the tool does and what it returns. Only minor gaps remain (not-found behavior, auth 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?

There is a single parameter with 100% schema coverage, so the schema already documents userId fully. The description adds nothing about the ID's format or origin, 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?

States a specific verb and resource ('Get details for a single user') scoped 'by ID', which implicitly contrasts with the sibling search_users. It does not name the alternative explicitly, so it falls short of a 5.

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

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

Usage is only implied: lookup a single user when you already have an ID. There is no explicit when-to-use vs when-not-to-use guidance and no mention of search_users as the alternative for non-ID lookups.

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

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

With no annotations, the description carries the full burden and does disclose useful behavior: the exact return shape, the default limit of 50 and the max of 200. It omits ordering of results, behavior when a project has no tasks, and any permission requirements, which leaves real gaps for a read tool with zero 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?

Three short sentences, front-loaded with the core action and immediately followed by pagination mechanics. Nothing is padded, though the return-shape sentence is slightly compressed in a way that makes it a list of field names rather than an explanation.

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

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

There is no output schema, so including the return shape ({ items, total, limit, skip, hasMore }) is genuinely valuable and covers the main unknown. Combined with the limit bounds, an agent can call this correctly; only result ordering is left unstated, which is a minor gap for a list tool.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema and the baseline is 3. The description restates the limit defaults and names the pagination concept, but adds no semantics beyond what the schema already says about skip/limit.

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 ('List tasks for a project') plus the pagination scope, so the agent knows exactly what it enumerates. It does not mention the sibling search_tasks, which also returns tasks and could be confused with this one, so sibling differentiation is absent.

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

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

Usage is implied by the shape of the tool – enumerate tasks within a known project at paginated scale – but the description never says when to prefer it over search_tasks or how it relates to get_task. No exclusions or prerequisites are stated.

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

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

With no annotations, the description carries the behavioral disclosure burden and does well for a read-style list tool: it explains pagination defaults, maximum page size, and the return envelope. It does not state permissions, sorting, or filtering behavior, which keeps it from a higher score.

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 tight sentences. The core operation is front-loaded, and the return-shape and pagination defaults are included without waste.

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 list tool with full schema coverage and no output schema, the description is nearly complete: it explains pagination and return fields. It lacks only broader routing guidance about related activity tools.

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

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

Schema description coverage is 100%, so the schema already documents serviceId, skip, and limit. The description adds useful context about defaults and maximum limit, but mostly reinforces structured information rather than adding new 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 and resource: list activities for a service. It is clear what the tool does, though it does not distinguish itself from sibling tools such as create_activity, update_activity, or bulk_update_activity_status.

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

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

The description implies usage by naming the service-scoped activity listing operation and pagination behavior. However, it gives no explicit guidance on when to use this tool versus related tools for activities or service details.

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. It usefully discloses sort order (newest first) and the data model rationale (time-series entries, not a task field), but says nothing about pagination, result size, or read-only safety profile for an unbounded history 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?

Two tight sentences, front-loaded with the action and ordering, followed by a rationale sentence that genuinely earns its place by explaining why this tool exists separately from update_task.

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-param read tool with no output schema and no annotations, the description covers intent and ordering but leaves the return shape and pagination/limit behavior unspecified, which matters for a potentially long history list.

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 projectId and taskId are already documented in the schema. The description adds no syntax, format, or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource: lists the progress (seguimiento/follow-up) history for a task, newest first. That clearly separates it from the mutation siblings create_task_progress/update_task_progress, though it never names an alternative explicitly.

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

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

The note that task progress is a time-series and that update_task rejects PercentComplete implies when this tool is needed (reading history rather than writing a single field), but there is no explicit when-to-use vs. sibling guidance or mention of prerequisites such as whether the task 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 and does so: it discloses the underlying data model (ONE total per user+task+date), the destructive implication of mode "set" (replaces) including that 0:00 clears the entry, and that the response echoes previous and new totals. It also states authorization constraints (Company Admin or Full Access license for another user) and that hours are attributed to that user, which is exactly the kind of side effect an agent needs before mutating data.

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

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

Four sentences, each carrying distinct information, with the core action front-loaded and the constraints following. It is dense but not padded; the only cost is that the prerequisite and authorization clauses are packed tightly enough to need a careful read.

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 eight parameters and no output schema, the description covers the data model, mode semantics, clearing behavior, return-value shape, assignment prerequisite, project-status gate, and license requirement. An agent has everything needed to call this correctly without further probing.

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 mechanical definitions are already handled. The description goes beyond the schema by explaining the persisted-total semantics behind mode "add" vs "set" and the default/attribution behavior of userId, adding meaning rather than restating field 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?

Opens with a specific verb and resource: "Log actual worked hours on a task for one user and date," which is concrete and actionable. The phrase "actual worked hours" implicitly separates it from effort/planning tools, but it never names update_task_effort or create_task_progress, so differentiation from the closest siblings 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?

Gives real preconditions an agent would otherwise get wrong: the user must be assigned to the task (TaskMembers via update_task) and the project status must permit time entry, with closed projects blocking it. It also clarifies the add vs set decision and when a different userId is permissible. It stops short of naming an alternative tool for the adjacent effort/progress 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?

With no annotations, the description carries the full behavioral burden and does so thoroughly: it lists allowed filter operators and pipeline stages, banned stages such as $lookup, $merge, and $out, hard limits for list and aggregation operations, and projection restrictions. It effectively signals a read-only query surface and discloses key operational constraints an agent needs before invoking it.

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 appropriately structured for a complex query tool. The first sentence is front-loaded with purpose and scope, and the subsequent sections group operations, constraints, key fields, and custom-field guidance cleanly.

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 complexity, eight parameters, nested objects, and absence of an output schema, the description is complete enough for an agent to invoke it correctly. It covers operation semantics, query capabilities, restrictions, limits, custom-field handling, and alternatives for large embedded arrays.

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 adds substantial meaning beyond the schema by mapping each operation to its relevant parameters and constraints. It explains allowed where operators, pipeline restrictions, sort behavior, limit maxima, and customFields query patterns, which materially improves correct invocation.

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: run a custom query against ITM DataMart, MongoDB-backed, for advanced analysis beyond typed tools. This clearly distinguishes it from typed sibling tools such as get_project or search_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?

It clearly frames usage as 'advanced analysis beyond typed tools' and routes agents away from projecting full embedded arrays toward dot notation or subcomponent tools. It also points to get_custom_fields and get_custom_field_options for field metadata, though it does not enumerate explicit when-not cases for every operation.

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 disclosure burden. 'Find' and 'Returns' imply a read-only, non-destructive operation and the return fields are enumerated, but pagination defaults/limits, sort behavior, and any auth or rate-limit constraints are left entirely to the schema or unstated.

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

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

Two tight sentences, zero waste, with the core capability stated first and the return shape second. Nothing is redundant or buried.

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

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

No output schema exists, and the description compensates by enumerating the returned fields (id, name, status, progress, dates, managers). Combined with full schema coverage on inputs, an agent has enough to call it correctly; only pagination behavior is left implicit.

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 each of the 8 parameters (skip, limit, sort, query, dateFrom, dateTo, status, type) is already documented. The description's 'Filterable fields' list loosely maps to these but adds no syntax or format detail beyond what the schema provides, 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?

States a specific verb ('Find') and resource ('projects') plus the filter dimensions and the returned fields. It is distinguishable from siblings like get_project or search_tasks by name and description, though it doesn't explicitly name a sibling to contrast with.

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

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

Usage is only implied by the filter list; there is no explicit when-to-use guidance nor any mention of alternatives such as get_project (single fetch) or query_datamart (aggregation). An agent must infer that this tool is for filtered discovery rather than single-record retrieval.

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 behavioral burden. 'Find' weakly implies a read-only operation, but the description does not state safety, permissions, result limits, pagination behavior, or whether matching is exhaustive.

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

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

Two sentences with no wasted words, and the primary purpose is front-loaded. The second sentence is a compact and useful analogy.

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 search tool whose parameters are fully documented in the schema, the description is mostly complete: it identifies the searchable dimensions and gives an analogous sibling. It omits the return shape and pagination behavior, but the purpose is clear enough 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?

The input schema has 100% description coverage for all eight parameters, so the schema already documents pagination, sorting, and filter semantics. The description names four filter dimensions but adds no syntax or format details beyond the schema, making the baseline 3 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 and resource ('Find services') and lists the main filter dimensions. It distinguishes the tool from search_projects via the services-vs-projects scope, but does not explicitly contrast it with get_service or the list_* service siblings.

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

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

The analogy to search_projects gives implied usage context: this is the service-scoped search counterpart. However, it does not state when to use this instead of get_service, whether it is preferable for broad discovery, or any exclusions or 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?

With no annotations to lean on, the description carries the burden well: it discloses DataMart eventual consistency with up to 60 seconds of staleness and the default/max result size. It does not explicitly state that the operation is read-only or how results are ordered.

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

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

A single dense paragraph, front-loaded with scope, then semantics, then return shape and consistency caveat. Every sentence adds information an agent would otherwise lack.

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 nine-parameter search with no output schema, it supplies the return envelope structure and the consistency caveat, plus the fallback to get_task. Ordering behavior and the fact that all filters are optional/no-query-returns-everything are not stated.

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

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

Schema coverage is 100%, so all nine parameters are already documented in the schema. The only real addition is that filters combine with AND; the limit default/max restates the schema verbatim.

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?

"Search tasks across all projects in the account" gives a specific verb, resource, and cross-project scope, which separates it from list_project_tasks (single project) and get_task (single record) among its 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 explicitly routes the agent to get_task when a confirmed single-task state is needed, which is a genuine alternative-selection rule. It stops short of stating when to prefer list_project_tasks over this cross-project search, so the guidance is clear but not exhaustive.

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 present, the description carries the full burden. It does disclose useful behavior beyond the schema: the returned fields, the fact that non-login users have an empty EmailAddress, and the backend used. It omits pagination/truncation behavior relative to the limit parameter, result ordering, and any permission or rate-limit constraints, leaving meaningful gaps for a search tool.

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

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

Three short sentences, front-loaded with the core purpose followed by return fields and then the non-login caveat. Dense and purposeful, though the TaskManagers/TaskMembers reference is slightly compressed and could be clearer about where that field appears.

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, so spelling out the return fields and the empty-email edge case is genuinely necessary and done well. It is not fully complete because the interaction between the limit parameter and result truncation is never explained, which matters for a search endpoint.

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

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

Schema coverage is 100%, so both query and limit are already documented, and the description adds only marginal meaning (email is the username, plus case-insensitive matching restated from the schema). The baseline of 3 applies when the schema does the heavy lifting and the description contributes little extra parameter guidance.

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

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

Opens with a specific verb and resource (find team members by name or email) and states the returned fields, which distinguishes it cleanly from the get_* siblings that fetch a single entity. It stops short of explicitly naming get_user as the single-record alternative, but an agent can infer the search-vs-fetch distinction from the name and description.

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 real routing context: it specifies projected v2 REST search rather than DataMart, which is a direct disambiguation from the query_datamart sibling. It also tells the agent what to do next with non-login users (address by UserId), but offers no explicit exclusions such as when to prefer get_user over search.

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 burden alone; it does disclose the key behavioral trait that this is a partial PATCH update rather than a full replace. It omits permission requirements, what happens when an unsupported field (KindId/ParentId) is sent, and whether changes are reversible, so meaningful 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?

Two tight clauses with no filler; the PATCH/partial-update rule is front-loaded and the status-entity caveat follows. Nothing is wasted, though the second clause is slightly cryptic without 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 12-parameter mutation tool with no annotations and no output schema, the description covers the update semantics and one important domain gotcha. It does not cover error behavior for unsupported fields or what the response contains, leaving real gaps for a tool of this complexity.

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 every field, including the 'NOT SUPPORTED' notes on KindId and ParentId. The description's 'send only the fields to change' phrase adds real partial-update semantics, but it adds no field-level meaning beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Update activity fields via PATCH') and the operation's core constraint ('send only the fields to change'). The resource ('activity') distinguishes it from update_task/update_service siblings, though no sibling is named 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 PATCH partial-update guidance tells the agent how to call it, and the note that activity statuses live under the 'activitystatuses' entity steers ID lookup. However, it never says when to use this versus bulk_update_activity_status or create_activity, which are the obvious adjacent choices.

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, so the description carries the full burden. It discloses useful behavior (PATCH semantics, automatic normalization of localized IDs), but says nothing about permission requirements, whether status changes trigger side effects/workflows, or what happens when an 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?

Two short sentences, front-loaded with the core action and the partial-update rule, followed by the ID-lookup pointer. No filler, no redundancy with the schema.

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

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

Adequate for a 7-param mutation with full schema descriptions, but with no annotations and no output schema the description should say more about consequences and return behavior — e.g. whether an empty body is a no-op, whether clearing a field is possible (additionalProperties: false, no null handling stated).

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value beyond the schema by explaining that only changed fields need sending (clarifying that the five optional params are optional-in-practice) and where to source the numeric TypeId/StatusId values. It does not define the Resolution field's semantics.

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

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

States a specific verb+resource (update issue fields) and the mechanism (PATCH), which an agent can distinguish from create_issue and the task/project updaters in the sibling list. It does not explicitly name a sibling it is *not*, so it falls short of a 5.

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

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

Gives concrete operating guidance: 'send only the fields to change' defines partial-update usage, and it names get_reference_data with the exact entity keys ('issuestatuses', 'issuetypes') for resolving TypeId/StatusId. No explicit when-not-to-use or error/precondition guidance, which keeps it below 5.

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

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

No annotations are provided, so the description carries the full burden. It does disclose PATCH/partial-merge semantics, which is genuine behavioral information beyond the schema, but it omits permissions, whether omitted fields are left untouched or cleared on dependent fields, and what the call 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?

A single compact sentence with the mutation and the partial-update instruction front-loaded. Nothing is wasted, though the sentence is thin enough that it could afford one more clause.

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 eight-parameter mutation tool with no annotations and no output schema needs more: required projectId, the status-field alias, and any side effects or response shape are left unaddressed.

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

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

Schema coverage is 100%, so every parameter is already documented in the schema. The description only adds the general rule that only changed fields should be sent, without addressing the StatusId/ProjectStatusId alias ambiguity 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?

States a specific verb and resource ('Update project fields') clearly enough that an agent knows this mutates an existing project. It does not differentiate from siblings like update_task or update_risk beyond the resource name, but the resource noun does most of the work.

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

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

The clause 'send only the fields to change' implies partial-update usage, which is real guidance. However, it never says when to use this versus create_project or update_project_progress, and gives no 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 must carry the full behavioral burden. It usefully discloses that omitted fields are left unchanged, but says nothing about whether the entry must exist, whether projectId and progressId must be consistent, permission requirements, or irreversibility of the change.

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

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

Two short sentences, both front-loaded: the mutation semantics first, the prerequisite lookup second. Nothing is wasted or repeated from the schema.

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

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

For a 7-parameter partial-update tool with no annotations and no output schema, the description covers what the tool does, which fields are optional, and how to get the required ID. It is short of full coverage only because it omits mutation-safety context and doesn't describe what is returned on success.

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

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

Schema coverage is 100% and every property is documented with bounds (0-100 percentage, ISO 8601 date), so the schema does the heavy lifting. The description's only extra is pointing to get_project_progress/includeEntries for the progressId lookup, which is cross-tool guidance rather than parameter 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?

States a specific verb and resource ('Update an existing project-level progress (Seguimiento) entry') and names the domain term, which distinguishes it from update_task_progress and create_project_progress in the sibling list.

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

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

Explicitly sets partial-update semantics ('send only the fields to change') and routes the agent to get_project_progress with includeEntries true to obtain the required progressId. It doesn't state a negative case (e.g. use update_task_progress for task entries), but the 'project-level' phrasing carries most of that weight.

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 disclosure burden. It adds genuinely useful behavior context—partial/merge update semantics ('send only the fields to change') and automatic normalization of localized IDs—but says nothing about permissions, validation failures on bad IDs, reversibility, or what is returned.

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

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

Two tight clauses with no filler, and the core operational instruction (send only changed fields) is front-loaded before the ID-discovery hint.

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

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

For an 11-parameter mutation with no annotations and no output schema, the description covers the essentials an agent needs: partial update semantics and where to source foreign-key IDs. It stops short of stating error/validation behavior or the response shape, which leaves a modest 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 100%, so all 11 parameters are already documented, making 3 the baseline. The description still earns credit above baseline by explaining the partial-update semantics for the optional fields and mapping the five *Id parameters to specific get_reference_data entity lookups, which the schema does not 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?

States a specific verb and resource (update risk fields) plus an operation-shape constraint: send only the fields to change. This separates it cleanly from create_risk, get_risk, and get_project_risks among the siblings without needing to open 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?

Gives concrete routing guidance: use get_reference_data with the exact entity names (riskstatuses, risktypes, riskimpacts, riskprobabilities, risklevels) to obtain the IDs this tool needs. It does not state exclusions (e.g., use create_risk for new risks) or prerequisites like permissions, so it falls short of fully explicit when/when-not guidance.

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

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

With no annotations, the description carries the full burden. It usefully discloses PATCH semantics and partial update behavior, but it does not describe permissions, side effects, reversibility, or what the operation 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?

Two compact sentences, with the update mechanism and partial-update instruction front-loaded. Every sentence adds useful information without 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?

The schema is rich and the description covers update mechanics, but this is a mutation tool with no annotations and no output schema. It should also clarify the return value or at least the expected result of a successful update.

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 schema already documents all parameters. The description adds genuine meaning beyond the schema by explaining partial updates and telling the agent that StatusId/ProjectStatusId values come from get_reference_data entity "projectstatuses".

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: update service fields, via PATCH. It is clear enough to distinguish from create_service and get_service, though it does not explicitly name those 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 instruction to send only fields to change makes the intended partial-update usage clear, and the status ID reference points to supporting data. However, it does not state when not to use this tool or explicitly compare it with 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, the description carries the safety/behavior burden and discloses meaningful traits: PATCH partial update, Waterfall-only KindId/ParentId changes, the milestone date-equality requirement, and AutomaticProgress side effects on progress entries. It still omits permission requirements, reversibility, and response behavior, so it is not fully complete.

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

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

Four dense sentences front-load the core PATCH/partial-update rule, then spend the remainder only on non-obvious constraints. No filler or repetition; every sentence adds operational value.

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

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

For a 14-parameter mutation tool with no annotations and no output schema, the description covers the most important side effects and Waterfall-only constraints while the rich schema documents all fields. It is nearly complete, but still lacks permission, error, and response 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 coverage is 100%, so the baseline is 3 even without description-added parameter detail. The description earns a 4 by clarifying KindId vs TypeId, ParentId moving under a summary task, and StatusId's interaction with AutomaticProgress and percentComplete.

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: update task fields via PATCH, with partial-update semantics. The KindId/ParentId/status details make clear this is a field-update tool, not a progress or bulk-status operation, but no sibling tool is explicitly named for 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?

Implies when to use it through 'send only the fields to change' and special-case rules, but never names alternatives such as update_task_progress or bulk_update_task_status or states when not to use this tool. Guidance is adequate but leaves alternative selection 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, the description carries the full burden and does so well: it discloses non-effects (no worked-time logging, no billing or accepted-effort changes), preservation semantics ("Unlisted users stay unchanged"), and a recompute side effect tied to taskTotalEstimate. It stops short of stating permission requirements or what the response contains, which keeps it off a 5.

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

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

Four compact sentences with zero filler, and the core purpose plus the negative scope are front-loaded. It is dense to the point of reading as a clause list, which costs a little readability but wastes no 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 nested-parameter mutation tool with no annotations and no output schema, the definition covers purpose, prerequisites, side effects and recompute rules. The remaining gap is response shape and error/permission behavior, but with annotations absent and no output schema the description is close to sufficient.

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

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

Schema coverage is 100% with nested objects fully documented, so the baseline is 3. The description adds genuine meaning beyond that by explaining the conditional behavior of taskTotalEstimate — when supplied it wins, otherwise the total is derived from user and unassigned-category estimates — which is not inferable from the schema alone.

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 ("Set planned effort for assigned users") and immediately delimits scope against adjacent operations by saying it never logs worked time or touches accepted effort/billing. An agent can distinguish it from log_time_entry, get_task_effort and update_task without opening any schema.

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

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

Gives an explicit prerequisite workflow ("Find assignees with get_task_effort and assign missing users with update_task first") and an explicit exclusion ("Regular tasks only"). It names the sibling tools to call before this one, which is exactly what an agent needs to sequence a multi-tool task.

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. It usefully discloses partial-update semantics, which is the key behavioral trait for a PATCH tool, but says nothing about permission requirements, side effects of changing percentage, failure modes when progressId does not belong to the task, or the response shape.

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

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

Two short sentences with the mutation semantics front-loaded and the ID-discovery hint second. Nothing is redundant and no sentence could be removed 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 an eight-parameter mutation tool with no annotations and no output schema, the description covers identity, partial-update behavior, and ID lookup, but omits validation expectations (e.g. progressId must belong to taskId/projectId) and any indication of what a successful call returns.

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

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

Schema description coverage is 100%, so every one of the eight parameters is already documented in the schema, including ranges and ID provenance. The description only reinforces the optional/partial nature of non-required fields; baseline 3 is appropriate.

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

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

States a specific verb plus resource ('Update an existing task progress entry') and disambiguates the Spanish term 'seguimiento/follow-up', which separates it from create_task_progress and update_project_progress by name. It does not explicitly name the sibling it is not, but the resource scoping is unambiguous.

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

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

Gives actionable PATCH guidance ('send only the fields to change') and a prerequisite step for the required progressId via list_task_progress. It stops short of exclusions, e.g. that status-only changes belong to bulk_update_task_status rather than here.

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