Cogmento MCP by usefulapi

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds useful behavioral context with the default grouping note and the GET endpoint, but it does not describe the response structure or any auth/rate-limit constraints.

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

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

The description is compact and front-loaded, with the core aggregation behavior stated first. The endpoint reference is slightly redundant but not harmful.

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

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

With no output schema, the description should do more to explain what the aggregate response contains. It says 'sums and counts' but does not specify the return shape or grouping behavior beyond the default note.

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 mentions the field parameter and gives an example, but adds no extra semantics for filters 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+resource: sums and counts deals, grouped by a field. It is clear what the tool does, but it does not distinguish itself from sibling tools such as cogmento_get_deal_pipeline_summary or cogmento_list_deals.

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 aggregation phrasing and the example field=stage, but there is no explicit guidance about when to use this tool versus listing deals or getting a pipeline summary. No exclusions or alternative routing are provided.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, and the description earns credit by explaining why: it stamps completer identity and timestamp, and a recurring task spawns its next occurrence, so repeat calls are not neutral. It still doesn't address permissions or error behavior for an unknown/already-complete task.

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 WRITE marker and the action, then the side effect, then the endpoint. Zero filler.

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

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

No output schema exists, and the description covers the relevant return-side effect (who/when stamp, next recurrence) for a single-parameter mutation. Missing only failure modes (nonexistent task, already completed) and required permissions.

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

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

With a single task_id parameter at 100% schema coverage, the schema already documents the UUID format and the endpoint path reinforces it. The description adds nothing about the parameter 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 and resource ('mark a task complete') plus the exact endpoint POST /tasks/{id}/complete/, which cleanly separates it from siblings like cogmento_get_task, cogmento_list_tasks, and cogmento_update_record_field.

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

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

The 'WRITE:' prefix signals this is a mutation and implicitly positions it against read siblings, but it never says when to prefer it over cogmento_update_record_field (e.g. setting a status field) or what preconditions exist. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so the description's 'WRITE' label mostly restates structured data. It adds the raw endpoint (POST /cases/) but says nothing about side effects, duplicate handling, required permissions, or what is returned on success.

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

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

Two terse fragments with the mutation signal front-loaded and no filler. It is efficient, though the brevity borders on under-specification rather than deliberate compression.

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 5-parameter mutation tool with no output schema and no annotation coverage of return values or permissions, the definition should say at minimum which fields are required and what a successful call yields. None of that is present, so an agent must open the schema to learn the single required field.

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

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

Schema coverage is 60% and the description supplies zero parameter information. The two most important fields, 'title' (the only required one) and 'description', carry no schema description at all, and the description does not compensate by explaining what a case needs to be created successfully.

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

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

States a specific verb ('create') and resource ('a case'), which cleanly separates it from the get/list/update siblings that share the 'case' resource. It does not explicitly contrast with cogmento_create_company/contact/deal, but the resource noun makes the distinction obvious enough.

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

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

There is no guidance on when to create a case versus using another tool, no prerequisites, and no mention of what must exist beforehand. The 'WRITE:' prefix is the only signal, and that is a mutation marker rather than usage guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds the 'WRITE' marker and the underlying POST endpoint, which corroborates rather than extends the annotations; it says nothing about duplicate-name behavior (relevant given idempotentHint=false) or error handling.

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 very short sentences, front-loaded with the write marker and no filler. The endpoint path is mildly redundant with the annotations but not wasteful enough to penalize heavily.

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?

Annotations fully cover the safety semantics and no output schema is needed, so the core call contract is discernible. However, with five parameters and only partial schema coverage, the description leaves an agent without field-level guidance or any note on what a successful create 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 60%, and the required 'name' parameter has no description in the schema or the tool description. The description adds no meaning about any of the five fields, so it fails to compensate for the uncovered parameters.

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

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

States a specific verb and resource ('create a company') and flags it as a write operation, which clearly separates it from get_company and list_companies. It does not explicitly distinguish it from sibling create_* tools (create_contact, create_deal), but the resource name does that implicitly.

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

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

No guidance on when to use this versus alternatives such as cogmento_create_contact or cogmento_update_record_field, and no prerequisites or preconditions are stated. The agent must infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the "WRITE" prefix mostly restates structured data. The description does add the endpoint (POST /contacts/) and confirms the two required fields, but stays silent on the meaningful trait implied by idempotentHint=false: that repeat calls create duplicate records, and on what the response 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 short fragments, front-loaded with the write marker and the essential required fields, with zero padding. It is terse rather than bloated, though the telegraphic style leaves room it could have used productively.

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 8-parameter creation tool with no output schema, the description omits four of the parameters, says nothing about the returned identifier for the newly created contact, and gives no duplicate-handling behavior. An agent would have to inspect the schema and guess at the response.

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

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

With 50% schema description coverage, half the parameters (tags, rating, description, middle_name) are undocumented in both schema and description. The description only re-states which fields are required versus optional, information the schema's required array already carries, so it adds no compensating semantics.

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

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

The description opens with a specific verb and resource ("WRITE: create a contact"), which cleanly separates it from the create_company/create_deal/create_case siblings. It does not explicitly name alternatives, but the resource noun is unambiguous enough that an agent can route on it.

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

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

There is no guidance on when to use this versus cogmento_update_record_field, or whether to check for an existing contact via cogmento_list_contacts first. Required-vs-optional fields are stated, but that is input contract, not usage context.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered by structured data. The description's "WRITE" merely restates readOnlyHint=false, and it omits genuinely useful behavior: whether duplicate titles are rejected, what happens to unspecified fields, and what the response 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 fragments, front-loaded with the operation type, so there is no padding. But the brevity is under-specification rather than efficiency: the raw HTTP endpoint ("POST /deals/") consumes space without helping an agent decide or call correctly.

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 six-parameter mutation tool with no output schema and partial parameter documentation, the description should carry meaningful weight. It instead leaves the agent without required-field emphasis, creation semantics, or any notion of what is returned.

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

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

Schema description coverage is only 67%, and the description adds nothing about any of the six parameters. It does not mention that 'title' is the sole required field, nor clarify deal-specific fields like amount, rating, or close_date beyond what the partial schema already says.

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

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

The description gives a specific verb and resource ("create a deal"), so the basic action is unambiguous. However, it offers no differentiation from the many sibling create_* tools beyond the name itself, and never says what a deal is or how it relates to contacts, companies, or stages.

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

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

"WRITE:" signals a mutation, but there is no guidance on when to use this versus cogmento_update_record_field or the related create_* tools, nor any prerequisites such as required permissions or whether a contact/company should exist first. The agent must infer all of this.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only "POST /tasks/", which restates the obvious mutation, and says nothing about validation failures, required authorization, or what happens to duplicate titles.

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 very short sentences with no filler, and the action is front-loaded via the "WRITE:" marker. However, the brevity reads as under-specification rather than disciplined conciseness, leaving no room for the guidance 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 five-parameter mutation tool with no output schema, the description says nothing about the returned record, whether the required title is the only mandatory field, or error behavior. Annotations cover the write semantics, but the operational context is incomplete.

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

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

Schema description coverage is only 60% — title and description lack any schema descriptions, and the description text supplies no parameter meaning at all. An agent gets no help understanding which fields matter, whether tags/rating are optional, or format expectations beyond the schema patterns.

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

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

States a specific verb and resource ("create a task") plus the underlying endpoint, so the action is unambiguous. It does not explicitly distinguish itself from the many sibling create_* tools, but the name already carries the resource distinction.

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

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

No guidance on when to use this versus alternatives such as cogmento_update_record_field or cogmento_complete_task, and no prerequisites or preconditions mentioned. The "WRITE:" prefix is the only usage signal, and that is already implied by the name and annotations.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the field inventory of what comes back and the underlying endpoint, which is useful context, but says nothing about auth requirements, response shape, or how it differs from the current-user call.

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 plus endpoint with zero filler. It is front-loaded with the resource and immediately lists the most salient returned fields, though the phrasing is a bare noun phrase rather than an actionable statement.

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

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

With no output schema, the description carries the burden of telling the agent what comes back, and the field list does that reasonably. However, for a simple zero-param read it still leaves the key open question — account vs. current user — unresolved, which is a meaningful gap given the sibling set.

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

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

The tool takes zero parameters, so there is nothing to disambiguate; baseline 4 applies. The description correctly implies a no-argument call by never mentioning any inputs.

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

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

The description names the resource and enumerates its contents (name, country, settings, billing plan, trial days, user count) but never states a verb — retrieval is only implied by the tool name. It also fails to distinguish itself from the sibling cogmento_get_current_user, which an agent may reasonably confuse with an 'account' lookup.

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

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

There is no guidance on when to call this versus cogmento_get_current_user or the various get_* record tools. The agent must infer usage entirely from the name and field list.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully structured. The description adds nothing beyond restating the HTTP route — no note on what happens for missing/unknown IDs, no pagination or error 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?

Extremely short and front-loaded with zero waste, but the terseness crosses into under-specification — the endpoint path is redundant given the tool name and 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, so the description carries the burden of describing return shape, yet it says only "one case record." For a single-resource fetch this leaves the agent guessing about the fields returned, without annotations or output schema to fill the 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% and the case_id property fully documents the UUID format and pattern, so the description is not required to explain parameters. Baseline 3 applies; the description adds no extra semantics.

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

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

"One case record" plus the raw endpoint GET /cases/{id}/ conveys a single-record fetch, and the singular distinguishes it from cogmento_list_cases. But there is no explicit verb and no statement of what a case is, leaving purpose implied rather than stated.

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

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

No guidance on when to use this versus cogmento_list_cases or cogmento_create_case, and no prerequisites mentioned. The only hint is the singular/plural contrast in the name itself.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that the response is a 'full' record including contacts and related records, which is useful payload context, but says nothing about permissions, missing-record behavior, or response volume.

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, front-loaded sentences with no padding. The trailing 'GET /companies/{id}/.' is REST implementation detail of marginal value to an agent, though it does confirm the id-scoped lookup pattern.

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

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

For a simple one-parameter read with annotations covering safety and no output schema, the description tells the agent what it gets back at a high level (full record plus contacts and related records). Only error/empty-result behavior is 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% with a single well-typed UUID parameter documented as 'Record id (UUID).' The description adds nothing beyond that, which is appropriate at baseline when the schema fully documents the parameter.

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

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

States a specific verb and resource ('One full company record') and implicitly contrasts a single-record fetch with the list counterpart via 'One full'. It doesn't explicitly name cogmento_list_companies as the alternative, so sibling separation is left partly to inference.

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

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

Usage is only implied: the tool requires a company_id, so an agent can infer it's for when the id is already known. The mention of contacts and related records hints at why to prefer it over a list call, but there is no explicit when-to-use/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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine context not in structured fields: the response is one record plus its related tasks, cases, calls, events and documents — a potentially large nested payload an agent should be prepared for. It stops short of noting error behavior or whether related collections are truncated/paginated.

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

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

Two short sentences, zero filler, and the highest-value information (what comes back alongside the record) is front-loaded before the endpoint detail.

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

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

For a simple single-parameter read with no output schema, the description covers what is returned and the annotations cover safety. The main remaining gap is failure/empty behavior and whether the related collections can be large or paginated.

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 a UUID format and pattern plus a description ('Record id (UUID)'), so the schema fully documents the single parameter. The description only reinforces it via the REST path GET /contacts/{id}/ and adds no format or provenance guidance beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource (fetch one full contact record) and clarifies scope by listing the related entities bundled in the response. It implicitly contrasts with cogmento_list_contacts via 'One full contact record', but never names the sibling explicitly.

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

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

Usage is only implied: an agent can infer this is for retrieving a single contact by id rather than listing them. There is no explicit when-to-use/when-not guidance, no mention of the list_contacts alternative, and no note on what to do when the id is unknown or not found.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond them by naming the REST endpoint (GET /auth/user/) and enumerating the returned fields, which matters because no output schema exists.

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 identity of the resource front-loaded and the field list immediately after. The trailing 'GET /auth/user/' fragment is marginally useful for endpoint mapping but adds no semantic value for tool selection.

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

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

For a zero-parameter read of a single object, the description covers what is returned (five named fields) in lieu of an output schema and signals the read-only nature. Only auth-failure behavior is left unstated, which is a minor gap for a self-identity call.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to compensate for. No parameter information is omitted or contradicted.

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-less but precise retrieval: 'The Cogmento user this API token belongs to', and enumerates the returned fields (id, name, email, timezone, account id). The 'API token' framing clearly separates it from cogmento_get_contact or cogmento_get_account, 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?

Usage is only implied: an agent can infer it should call this to learn the identity of the token owner. There is no explicit when-to-use statement and no guidance on when to prefer cogmento_get_account or cogmento_get_contact instead.

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

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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds meaningful value by disclosing the shape of the return payload (deal plus contacts, products, related records), which matters because there is no output schema.

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

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

Two short sentences with the payload description front-loaded and the REST path appended as a reference. There is no waste, though the raw endpoint adds little for an agent that already has 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 single-record read with full schema coverage and annotations, the description supplies the missing piece an agent needs: what the returned record contains. Nothing critical is absent, though name-based sibling routing is not spelled out.

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

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

Schema coverage is 100% and the single deal_id parameter is documented in the schema as a UUID record id. The description adds no syntax or meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific resource ('One full deal record') and enumerates what it returns (contacts, products, related records), which implicitly distinguishes it from cogmento_list_deals. It never names the sibling explicitly, so it stops just short of full differentiation.

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

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

The singular 'one full deal record' plus 'GET /deals/{id}/' implies this is the single-record fetch versus the list tool, but there is no explicit when-to-use statement or named alternative. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is free. The description adds real value beyond that by disclosing the shape of the result — per-stage counts and monetary totals — which matters because there is no output schema.

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

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

Three short sentences: the output shape first, the filter behavior second, the endpoint last. No filler and nothing redundant.

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

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

For a simple read-only aggregate with annotations and a fully documented schema, the description covers what is computed and how filters affect it. It stops short of clarifying edge cases such as whether stages with zero deals appear or how multi-currency totals are handled, which an agent might reasonably want.

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

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

Schema description coverage is 100% and there is only one optional parameter, so the schema already documents the filter object, operators and AND semantics in detail. The description only restates that filters are optional and narrow the counted deals, adding little 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: totals of deal count and value grouped by pipeline stage, plus the endpoint GET /deals/summary/. It is distinguishable from list/CRUD siblings but never contrasts with cognmento_aggregate_deals, the nearest analogue, so an agent must infer the difference.

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 sentence 'Optional filters narrow the deals counted' implies the tool is for filtered rollups rather than raw listing, but there is no explicit when-to-use guidance and no mention of when to prefer cogmento_aggregate_deals or cogmento_list_deal_stages instead.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds only the endpoint path, which is essentially a restatement of the read operation and provides no additional context about error handling, permissions, or lookup behavior.

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

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

The definition is front-loaded and extremely brief. The endpoint fragment is mildly redundant with the title, but there is no filler or wasted prose.

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

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

For a simple get-by-ID tool with clear annotations and a fully described parameter, the description is minimally adequate. It omits what the 'one task record' contains and does not address not-found or error behavior, but those gaps are relatively minor for this tool type.

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

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

Schema coverage is 100% and the single task_id parameter is fully documented as a UUID. The description’s '{id}' path notation aligns with the schema but adds no new semantic detail beyond what the schema provides.

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

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

The description states the resource ('One task record') and implies the retrieval operation via 'GET /tasks/{id}/'. It is clear enough to distinguish a single-task fetch from list_tasks, though it does not explicitly name or contrast with siblings.

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

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

There is no guidance on when to use this tool versus alternatives such as cogmento_list_tasks or cogmento_get_case. The single-record scope is implied but no explicit selection criteria or prerequisites are given.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds that this is a GET /templates/ call returning field metadata per record type, which is meaningful since there is no output schema. Auth, rate limits, and pagination behavior are unstated, keeping it below 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?

Two compact sentences: the first front-loads what is returned and for which record types, the second immediately gives the actionable use case. No filler or restatement of the title beyond what's necessary.

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

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

For a zero-param read tool with no output schema, the description adequately conveys what comes back (field names, labels, types, options per record type) and why. Only minor omissions like response shape details or empty/error behavior keep it from a 5.

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?

Zero parameters, so the baseline of 4 applies; the description does not need to explain inputs and correctly doesn't waste words on them.

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 resource (account templates / field definitions) and enumerates the exact content returned: names, labels, types, options, per record type (contacts, companies, deals, cases, tasks). This clearly separates it from the record-fetching siblings like cogmento_get_account or cogmento_list_contacts, though the verb itself is left implicit in a noun phrase.

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 states the use case: 'Use it to learn the custom field names for filters, creates and field updates,' which effectively points the agent at the create/update/filter siblings as downstream consumers. No explicit exclusions or when-not conditions, but none are really needed for a single zero-param metadata endpoint.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the useful default-order behavior ('most recent first') and the source of records, but says nothing about result shape or pagination behavior beyond what the schema states.

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

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

Front-loaded and essentially one sentence plus an endpoint marker; nothing is padded. The raw 'GET /calls/' fragment is of marginal value to an agent but does not dilute the definition.

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

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

With no output schema, the description carries some burden for describing what comes back, and it only says ordering and record types, not the pagination contract or returned fields. Annotations cover the safety profile and the schema covers the parameters, so the remaining gap is moderate rather than severe.

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

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

Schema description coverage is 100%, covering sort, limit, start with next_start paging, and the filter operator/date-format semantics, so the baseline is 3. The description's 'most recent first' implicitly documents the default sort but adds no filter or paging guidance of its own.

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

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

Names the resource (the account's call records) and its default ordering (most recent first), and clarifies the two sources covered: manual logged calls and browser-dialer calls. It doesn't need to differentiate against a sibling because no other call-listing tool exists, so this is clear without being a model of 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?

Usage is only implied: an agent can infer this is the way to enumerate all calls, but there is no statement of when to prefer it, what cannot be done with it, or which sibling to use for related data. The trailing 'GET /calls/' hints at the underlying endpoint but adds no decision guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the endpoint and the set of case fields; it says nothing about pagination behavior, result caps, or default page size beyond what the schema already states.

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

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

A single tight sentence plus the endpoint reference, front-loaded with the verb. Nothing is wasted, though the trailing 'GET /cases/' conveys little to an agent that already has the tool.

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

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

For a read-only list tool with 100% schema coverage and safety annotations, the description covers purpose, resource scope and filterable subject matter. Response shape is the only real gap, and a list endpoint's return form is largely implied.

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

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

Schema description coverage is 100%, so the schema fully documents sort, limit, start and the filter object. The description's field list (title, close date, assigned users, deal, company) marginally extends the schema's generic examples by naming case-specific fields, but adds no operator or format 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?

States a clear verb+resource ('List or search cases') and disambiguates the resource as 'support or project cases', listing the fields that characterize a case. It is distinguishable from cogmento_get_case by the list/search framing, though it never names that 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?

'List or search cases' implies when to reach for it (browsing or filtering the case collection), but there is no explicit when-not, no mention of when to prefer cogmento_get_case or cogmento_create_case, and no guidance on when to use filters vs. sort.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the raw endpoint 'GET /companies/', which gives no behavioral context such as pagination defaults, the maximum page size, or result ordering.

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 fragments, front-loaded with the action and resource. Nothing is wasted, though the trailing raw HTTP endpoint is low-value for an agent that never issues HTTP calls directly.

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?

Schema and annotations together carry parameters and safety, leaving the description thin but workable. With no output schema, the description never indicates the shape of the returned list or how next_start is surfaced, which is a real gap for a paginated listing 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 sort, limit, start and the filter structure are already fully documented in the schema. The parenthetical '(name, website, contacts)' loosely suggests filterable fields but adds no syntax or constraints beyond what the schema provides, 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?

States a specific verb and resource ('List or search companies') with a hint of what is searchable (name, website, contacts), which distinguishes it from cogmento_get_company and cogmento_create_company. It lacks any explicit naming of those siblings, so it stops short of full sibling differentiation.

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

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

No when-to-use guidance is given: nothing says to prefer cogmento_get_company when a specific ID is known, or cogmento_list_contacts for people rather than companies. 'List or search' implies two modes but never explains how to choose 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the underlying endpoint (GET /contacts/); it says nothing about default result ordering, whether a total count is returned, or what happens when filters match nothing.

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 verb and resource, followed by the searchable fields and an example. No filler, though the trailing 'GET /contacts/' is marginally useful for an agent that already has the tool bound.

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

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

All four parameters are optional and fully described in the schema, and annotations cover read-only safety, so the description does not need to carry much more. The main residual gap is the absence of any statement about the response shape (no output schema exists) or pagination follow-through.

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 sort, limit, start, and the nested filter object are all documented. The description adds one concrete example ('first_name contains Eric') that illustrates the filter operator pattern, but adds no new constraint or format detail beyond the schema 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?

States a specific verb and resource ('List or search contacts') and enumerates the searchable surface (name, email/phone channels, company). It is clearly the plural counterpart to the get_contact sibling, though it never explicitly contrasts with it or with list_companies.

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: 'List or search' plus a filter example signals when to use it. But there is no explicit guidance on when to pick this over cogmento_get_contact for a known ID, or how it relates to list_companies for cross-object queries.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the HTTP endpoint and the searchable field set but says nothing about pagination, result ordering defaults, or result volume beyond what the schema states.

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

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

A single front-loaded sentence plus the endpoint, with no filler. Slightly thin rather than verbose; nothing is wasted but the parenthetical field list could have been framed as filterable fields.

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

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

There is no output schema, and the description does not describe the return shape (deal records, paging via next_start, total counts). Annotations cover the read-only/open-world profile and the schema covers all four parameters, so the remaining gap is moderate but real.

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

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

Schema description coverage is 100%, with sort, limit, start and filters all documented in detail including the next_start paging hint. The description's field list hints at what can be filtered on, but adds no syntax or operator detail beyond the schema, 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 ('List or search') and resource ('deals'), plus the endpoint GET /deals/. The enumerated fields (title, amount, close date, assigned users, products) make clear this is the multi-record read, distinguishing it from cogmento_get_deal and cogmento_aggregate_deals, though it never explicitly names those siblings.

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

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

Usage is implied by 'list or search' plus the mention of filterable fields, but the description never says when to use this versus cogmento_get_deal (single record) or cogmento_aggregate_deals (aggregation), and gives no 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured fields. The description contributes only the 'account-wide' scoping note and the underlying path; it says nothing about ordering, whether stages are user-customizable, or whether archived stages are included.

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 core meaning front-loaded and no repetition of the title. The raw 'GET /deals/stages/' trailing fragment adds little for an agent and is the only 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 parameterless enumeration with full annotation coverage and no output schema, the description supplies enough to call it correctly. A brief note on what each stage record contains (name vs. id) would have closed the last 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly implies an unfiltered full listing, matching the empty input schema.

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

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

The description identifies a specific resource — the account-wide set of contact stages within a deal — and grounds it with concrete examples (Champion, Decision maker), so an agent knows exactly what enumeration this returns. It stops short of naming the paired sibling cogmento_set_deal_contact_stage, which would have made the purpose unambiguous against the rest of the toolset.

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: it is clearly reference data for valid stage values, and the existence of cogmento_set_deal_contact_stage suggests the natural follow-on, but the description never says 'call this before setting a stage' or states any alternative. An agent can infer the when, but must do the work itself.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the endpoint and the fact that the catalogue is shared/authoritative for deals and invoices, but says nothing about pagination semantics, result size, or ordering defaults beyond what the schema documents.

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 fragments with zero filler; the purpose and returned fields are front-loaded and the endpoint is appended as a lookup detail. Nothing 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 a read-only, zero-required-parameter list tool with a fully documented schema and no output schema, the description covers what it returns (name, prices) and its role in the data model. The only mild gap is that no output shape beyond two fields is hinted at, which is acceptable given the absence of an output schema.

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

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

Schema description coverage is 100% — sort syntax, limit range with default 25, start offset with next_start chaining, and filter field/operator/value are all spelled out in the schema. The description adds no parameter-level meaning on top, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the product catalogue') and even enumerates the returned fields (name, prices), plus the underlying endpoint GET /products/. It doesn't explicitly contrast with sibling list tools (list_deals, list_companies), but the resource name is unambiguous enough to separate it from the other twelve-plus list_* 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 clause 'that deals and invoices draw on' implies when this is relevant (pricing lookups, resolving product references on deals/invoices), but there is no explicit when-to-use or when-not-to-use guidance and no named alternative. Usage is inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered by structured data. The description adds the navigational context of the REST endpoint and the set of fields exposed, but says nothing about pagination behavior, default result count, or ordering — gaps the agent must infer.

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

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

Three terse fragments, front-loaded with the core action and field inventory. The trailing "GET /tasks/." is somewhat extraneous for an agent that cannot issue raw HTTP, but it is short enough not to bloat the definition.

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

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

For a zero-required-parameter read tool with 100% schema coverage, full annotations and no output schema, the description supplies what is missing: what the tool returns and which fields are searchable. Only the absence of any sibling routing (get_task vs list_cases vs list_deals) keeps it from being fully complete.

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

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

Schema description coverage is 100%, with sort, limit, start and filters all fully documented inline (including the next_start paging pattern and AND semantics for filters). The description only hints that filtering is possible via "Filter e.g. on due_date", adding essentially nothing beyond the schema, 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?

Clear verb+resource ("list or search tasks") plus an enumeration of the searchable/returnable fields (title, due date, completion date, assigned users, linked deal/contact/case) and the backing endpoint. It distinguishes itself from cogmento_get_task and cogmento_create_task by implication, but never names 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?

"Filter e.g. on due_date" gives a single concrete example of narrowing results, and the verb "search" implies retrieval rather than mutation. There is no explicit statement of when to use this versus cogmento_get_task for a single record, or versus cogmento_list_cases/list_deals for other entity types — usage is only 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?

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety/retry profile is covered. The description adds genuinely new information beyond them: the call has an attaching side effect ("The contact is attached to the deal if it is not already"). It stops short of saying whether an existing stage assignment is overwritten, which is exactly what destructiveHint=true implies, so it is good 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 short sentences, front-loaded with the WRITE marker, each carrying a distinct fact (action, side effect, endpoint). No redundant restatement of the title, 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 single-field mutation with full schema coverage and annotations carrying safety hints, this is nearly sufficient: it gives the required stage source and the contact-attachment side effect. The one gap is overwrite/merge semantics when the contact already has a stage in that deal.

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, including the constraint that stage comes from cogmento_list_deal_stages. The description restates that constraint but adds no format, casing, or behavioral detail about the parameters. 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?

Opens with an explicit verb+mode marker ("WRITE") and a specific resource: a contact's stage within a deal. It also names the sibling tool that supplies valid stage values (cogmento_list_deal_stages), so an agent can distinguish it from read siblings like cogmento_get_deal 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?

The description makes the prerequisite path explicit — the stage value must come from cogmento_list_deal_stages — which steers the agent to call that tool first. It doesn't state what to do when the contact is already staged or when the contact isn't associated with the deal, but it does name the relevant sibling.

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 annotations already marking the tool destructive, idempotent, and non-read-only, the description adds useful behavioral detail beyond them: the tool is a WRITE limited to one field, system fields are rejected, and custom field names must be sourced from cogmento_get_templates. It does not describe whether other fields remain unchanged or what errors look like, but that is a minor gap given 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?

It is four compact sentences with the operative verb and scope front-loaded. Every sentence adds information: examples, template lookup, system-field restriction, and endpoint form, with no redundant repetition of schema details.

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 4-parameter mutation tool with no output schema, the description covers the essential call semantics: what is written, which fields are invalid, and where valid custom field names come from. It could be slightly more complete about side effects on untouched fields or permission requirements, but the annotations already carry the safety profile.

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 already 100%, so the baseline is 3. The description adds value beyond the schema by explaining where valid field names come from (cogmento_get_templates) and which field names are refused (id, acl, private, timestamps), which directly informs the field_name parameter.

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

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

The description opens with a specific verb and scope: "WRITE: change a single field of a contact, company, deal, task or case". This clearly distinguishes it from create/get/list siblings and from broader record-level mutations, and it names concrete examples such as a deal's status or a contact's first_name.

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

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

It gives a clear when-to-use context (single-field changes) and an explicit exclusion (“System fields (id, acl, private, timestamps) are refused”), plus a prerequisite for custom fields (“Custom field names come from cogmento_get_templates”). It does not explicitly route agents away from specialized siblings such as cogmento_set_deal_contact_stage, so it is strong but not fully alternative-aware.

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