Accelo MCP by usefulapi

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

Adds real behavior beyond the readOnlyHint annotation: it pins the allowed HTTP method (GET only), declares the escaping is read-only, and states the response envelope is { meta, response } — valuable given there is no output schema. It omits rate limits, pagination semantics, and error behavior for invalid paths.

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 escape-hatch framing and the hard GET-only constraint before the mechanical path and return-shape details. 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 single-parameter passthrough tool with no output schema, the description covers everything needed to invoke it correctly: the method restriction, exact path format, query-string handling, worked examples, and the return envelope.

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 non-obvious meaning: the path must be the FULL path after the host, start with '/', and include the query string entirely. The two inline examples showing filter syntax ('?_limit=1&_filters=status(1)') go beyond the schema's single example.

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

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

States a specific verb and scope: 'GET any Accelo API path not wrapped by a dedicated tool.' It explicitly positions itself against the ~22 sibling get_/list_/create_ tools by defining itself as the fallback for what they don't cover, so an agent can route correctly 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?

Gives a clear routing rule ('paths not wrapped by a dedicated tool') plus an implicit restriction (READ-ONLY, only GET is allowed), which tells the agent when this tool cannot be used. It stops short of naming a specific sibling as the preferred alternative or spelling out fallback behavior when a dedicated tool does 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?

Annotations already declare destructiveHint=true, and the description adds real context beyond them: the POST /api/v0/activities endpoint, form-encoded body, and the {meta, response} return envelope. This is solid, but calling itself the 'highest-value safe write' sits in tension with destructiveHint=true and could understate risk to an agent.

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 mutation warning and compact at four short sentences. The 'highest-value safe write' clause is marketing filler that does not earn its place, but overall it is tight.

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

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

For a 9-parameter tool with no output schema, the description covers the endpoint, encoding, return shape, and the required target pairing. It does not explain the optional fields (fields, visibility, owner_type), but the schema covers those.

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

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

Schema description coverage is 100%, so every parameter is already documented. The description only restates the against_type + against_id pairing and their requiredness, adding little meaning the schema does not already carry — baseline 3.

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

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

The description names a specific verb (logs) and resource (an activity: note, email, call, or meeting) and states the object it targets. This is clearly distinguishable from siblings such as create_task, create_contact, or create_company.

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

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

It provides a concrete use case ('add a note/comment to a job or company') and frames the tool as the preferred lightweight write. However, it never says when to choose it over siblings (e.g. create_task or the generic accelo_request), so 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?

Discloses behavior beyond the annotations: it names the exact endpoint and encoding (POST /api/v0/companies, form-encoded) and the response shape { meta, response }, which is valuable given there is no output schema. The destructiveHint=true annotation already signals a mutating operation, and 'MUTATES Accelo data' is consistent with it. Missing auth requirements and rate/idempotency behavior keeps this from 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?

Front-loads the mutation warning, then endpoint, then return shape, then the update alternative — every clause carries information. The trailing parenthetical is dense and slightly awkward but not wasted text.

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

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

For a 6-parameter mutation tool with no output schema, the description supplies the endpoint, encoding, response envelope, and the update/delete routing note, while the schema covers all parameters. It lacks auth/permission expectations and failure behavior, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so every parameter (including the nested 'fields' bag) is already documented in the schema; the baseline is 3. The description adds the form-encoding detail and implies the typed fields are merged with 'fields' into the write body, but no per-parameter semantics beyond that.

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 — 'creates a new company (client organization)' — and marks it as a mutation up front. This clearly distinguishes it from sibling readers like get_company/list_companies and from other creators like create_contact or create_task.

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 useful routing context by noting there is no separate delete tool and that UPDATE is done by POSTing to /api/v0/companies/{id}. It does not mention the generic accelo_request sibling, which is the obvious fallback for non-create operations, so it stops short of full 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?

Annotations only provide destructiveHint=true; the description adds real behavioral context on top: the 'MUTATES' framing, form-encoded POST body, the two-step affiliation caveat, and the { meta, response } return shape. It does not cover auth/permission requirements or failure modes, so not 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?

Every clause earns its place: mutation flag first, endpoint second, the non-obvious affiliation caveat third, return shape last. No filler and nothing 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?

Even without an output schema, the description states the return envelope, and the schema fully documents inputs including the nested fields object. For a create tool with only destructiveHint, the agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, so all six parameters including the nested 'fields' bag are already documented in the schema. The description adds no per-parameter meaning, which is the expected baseline when the schema carries the load.

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: 'creates a new contact (a person)', disambiguating from the sibling create_company. It also pins the backing endpoint (POST /api/v0/contacts), so an agent knows exactly what operation this is.

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

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

No explicit routing guidance among siblings (e.g., when to prefer create_contact over accelo_request or create_company). It does supply a useful workflow constraint — company affiliation must be attached afterward via a separate affiliations call — which is implied usage context rather than a full when/when-not 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?

Annotations only declare destructiveHint=true. The description adds real behavioral context beyond that: the explicit 'MUTATES Accelo data' warning, the underlying endpoint (POST /api/v0/tasks), and that the body is form-encoded. It does not mention auth requirements or rate limits, so it stops short of 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 short sentences, front-loaded with the mutation warning and the attachment constraint. Every sentence carries distinct information — mutation, prerequisite, transport, response shape — with no redundancy.

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

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

Covers the mutation risk, the non-obvious attachment requirement, the endpoint and encoding, and even the response envelope ({ meta, response }) despite no output schema being defined. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantic meaning the schema lacks: that against_type and against_id form a mandatory pair expressing an attachment relationship, with example types (job, company, issue). That is more than restating field descriptions.

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

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

States a specific verb and resource ('creates a new task') and flags the operation as a mutation up front. The clarification that tasks are always attached to an object meaningfully separates it from sibling creators like create_activity, 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 description supplies a genuine prerequisite — tasks must be logged against an object, so against_type + against_id are mandatory — which tells the agent when the call is valid. It does not, however, state when to prefer this tool over create_activity or the other sibling create 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered and the description's job is lighter. It usefully adds the raw Accelo endpoint mapping and the envelope shape of the response, but says nothing about error behavior for a missing/invalid id or about rate limiting.

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, zero filler, and the core identity of the tool is front-loaded before the endpoint and return-shape 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?

With no output schema, the description compensates by naming the { meta, response } return envelope, and the tool's surface area is small (2 params, read-only). A brief note on behavior when the id does not resolve would have closed the remaining gap.

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

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

Schema description coverage is 100%, so both id and fields are fully documented in the schema, making 3 the baseline. The description adds no extra semantics for the fields parameter (e.g., cost of _ALL or field syntax) 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?

States a specific verb (Fetch) and resource (a single activity), and enumerates the concrete subtypes (note/email/call/meeting). The word 'single' plus the /activities/{id} endpoint cleanly separates it from the sibling list_activities.

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 rather than stated: fetching exactly one activity when you already have its id. It never names list_activities as the alternative for enumeration, nor mentions any prerequisites for obtaining the id, so routing 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds the raw Accelo endpoint (GET /api/v0/companies/{id}) and the response envelope shape ({ meta, response }), which is genuinely useful extra context absent from annotations. It stops short of noting error behavior for missing ids or rate limits.

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

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

Three short clauses, zero filler: purpose first, then the API mapping, then the return shape. Everything is front-loaded and nothing repeats the schema or annotations.

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

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

For a simple two-parameter read with full schema coverage and readOnly annotations, this is nearly complete; the return envelope is disclosed even without an output schema. Only the absence of any error/edge-case note (e.g., unknown id) keeps 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?

Schema description coverage is 100% and both parameters (id, fields) are fully documented in the schema, including even the '_ALL' syntax. The description adds no parameter-level detail beyond that, so the baseline of 3 applies.

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

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

Specific verb ('Fetch') plus resource ('a single company') with a clarifying gloss that it is a client organization in Accelo. The word 'single' implicitly separates it from the list_companies sibling, and the underlying endpoint is named, so an agent knows exactly what it retrieves.

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: a required id plus 'single company' signals a point lookup, not a search. There is no explicit statement about when to prefer this over list_companies, or when to reach for the 'fields' parameter versus the default payload, so the guidance is minimal but not misleading.

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, covering the safety profile, so the bar is lower. The description usefully adds the underlying Accelo API mapping (GET /api/v0/contacts/{id}) and the response envelope shape { meta, response }, but says nothing about error behavior or missing/invalid ids.

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

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

Two short sentences, front-loaded with purpose followed by implementation detail; no filler. Slightly terse, 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?

For a simple read-only single-resource fetch, the description plus annotations plus 100% schema coverage cover what an agent needs; the response envelope is even disclosed despite there being no output schema. Missing only error-case hints.

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 (id, fields) are already documented in the schema, including the _fields syntax and "_ALL". The description adds no parameter meaning 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 and resource ("Fetch a single contact (a person)") and the word "single" implicitly separates it from the list_contacts sibling. It stops short of naming alternatives explicitly, but 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?

Usage is only implied by "single contact" and the required id parameter; there is no explicit when-to-use, no exclusion criteria, and no pointer to list_contacts/search alternatives. Adequate but leaves the agent to infer routing.

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

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

readOnlyHint=true already covers the safety profile, and the description adds value beyond that by naming the underlying endpoint (GET /api/v0/invoices/{id}) and disclosing the { meta, response } envelope, which matters because no output schema exists. It says nothing about auth or error behavior for a missing id.

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

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

Three short sentences, zero filler, with the purpose front-loaded before the endpoint and return-shape details. Every sentence earns its place.

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

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

For a simple two-parameter read tool this is nearly complete, and the return envelope is disclosed in the absence of an output schema. Minor gap: it does not describe the contents of meta/response or failure 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 description coverage is 100%, so both 'id' and 'fields' are already documented in the schema; the endpoint template confirms 'id' is a path parameter but adds no new format or constraint detail. 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 ('Fetch a single invoice') and the scope word 'single' cleanly distinguishes it from the sibling list_invoices. An agent can tell this is a by-id retrieval 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?

Usage is only implied by the 'single invoice' scoping; the description never says when to prefer this over list_invoices or accelo_request, nor what happens if the id does not exist. Adequate but with a clear routing gap.

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?

readOnlyHint=true already establishes the safe-read profile, so the bar is lower. The description still adds useful context beyond annotations: the concrete endpoint and the return envelope shape '{ meta, response }', which tells the agent what to expect back. It stops short of noting pagination/error/auth behavior, but the read semantics are covered.

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

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

Three compact fragments, front-loaded with the action, followed by the endpoint and return shape. No filler; every clause carries information an agent can act on.

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

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

For a single-record read with readOnlyHint and full schema coverage, the definition gives enough to select and invoke it. There is no output schema, and the return envelope is named but not elaborated, which is the only remaining gap; acceptable for a simple GET.

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 (id, fields) are already documented in the schema, including the '_fields'/_ALL convention. The description adds no parameter-level detail beyond what the schema provides, so the baseline of 3 is correct.

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 (fetch) and resource (a single issue/support-service ticket), and the word 'single' disambiguates it from the sibling list_issues. It even pins the underlying API call (GET /api/v0/issues/{id}), so an agent can distinguish it from every other get_* sibling 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: 'single issue' suggests retrieving one record by id rather than listing, but there is no explicit when-to-use/when-not or named alternative (e.g., 'use list_issues to search'). The agent must infer the routing from the word 'single'.

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 readOnlyHint=true already covering the safety profile, the description adds genuinely new context: the underlying API route (GET /api/v0/jobs/{id}) and the { meta, response } return envelope, which matters because no output schema exists. It stops short of documenting auth needs, error behavior, or rate limits.

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

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

Three short, front-loaded sentences: purpose first, then API mapping, then return shape. Nothing is padded or repeated.

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

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

For a simple read-by-id tool, the description covers purpose, endpoint, and the return envelope, which compensates for the absent output schema. Only minor details (auth, error cases) are unstated, which is acceptable at 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 both id and fields are fully documented in the schema and the description adds no syntax or format detail beyond it. Baseline 3 is appropriate when the schema carries the parameter semantics.

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

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

States a specific verb (Fetch) and resource (a single job/project), and the word 'single' implicitly distinguishes it from the list_jobs sibling. It clarifies the domain term by equating 'job' with 'project', but never names list_jobs explicitly, so the differentiation is inferable rather than stated.

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

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

There is no explicit when-to-use or when-not-to-use guidance, but 'Fetch a single job' plus the required id parameter implies the retrieval-by-identifier case versus the listing case. Usage is implied rather than directed, and no alternatives or prerequisites are mentioned.

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

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

Annotations already declare readOnlyHint=true, and the description adds the exact HTTP method and endpoint (GET /api/v0/prospects/{id}) plus the return envelope { meta, response }, which is valuable because no output schema exists. It omits auth requirements and error behavior, but those are minor for a simple read.

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 purpose, then the API endpoint, then the return shape. Every sentence carries non-redundant information and there is no 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 single-item read with 100% schema coverage and a readOnlyHint annotation, the description supplies the missing pieces: the endpoint and the return envelope. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%: both id and fields are fully documented in the schema. The description adds no parameter-level detail beyond the {id} path template, so the schema does the heavy lifting and a 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, resource, and cardinality: 'Fetch a single prospect (sales opportunity).' The domain gloss in parentheses and the explicit 'single' distinguish it from list_prospects and other get_* siblings without needing to open their schemas.

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

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

The phrase 'Fetch a single prospect' gives clear context for when to use it (one record by id), but it does not explicitly name when-not to use it or point to list_prospects as the alternative for multiple records. Context is clear, though exclusions are absent.

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 establish readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful non-annotation context: the underlying endpoint (GET /api/v0/staff/{id}) and the response envelope ({ meta, response }), which matters because there is no output schema. It omits auth requirements, rate limits, and error behavior for an invalid id.

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

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

Three short, front-loaded sentences with no filler: purpose first, then endpoint, then return shape. Slightly terse, but nothing is redundant and an agent can parse it in one pass.

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 and a read-only annotation, the description covers purpose, target endpoint, and return envelope. The only meaningful gap is failure behavior (invalid/unknown id), which is minor at this complexity, and it usefully compensates for the absent 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%, so both the 'id' and 'fields' parameters are already documented in the schema, including the _fields syntax and '_ALL' option. The description only restates '{id}' in the URL template and adds no meaning 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?

Starts with a specific verb+resource ('Fetch a single staff member'), and the word 'single' implicitly distinguishes it from the sibling list_staff. It never names the sibling explicitly, so the differentiation is left to inference 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?

The description implies usage (retrieve one staff record when you have an id) but gives no explicit when-to-use, when-not-to-use, or alternative guidance. It does not tell the agent to prefer list_staff for enumeration or accelo_request for arbitrary endpoints, leaving routing to the reader.

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

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

The readOnlyHint annotation already establishes this is a safe read. The description adds the upstream endpoint and the envelope shape '{ meta, response }', which is useful for a tool with no output schema, but it says nothing about error cases (e.g. missing id) or field semantics.

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 core action and no filler. The API route/path is marginally useful, though the return-shape note is terse to the point of being cryptic.

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

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

For a simple single-record fetch with complete schema coverage and an annotation covering safety, the description is nearly sufficient; the envelope mention partially compensates for the absent output schema. Only error/edge behavior 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 both 'id' and 'fields' are fully documented in the schema itself. The description adds nothing beyond that, which is the expected baseline when the schema carries the load.

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 a single task'), which cleanly distinguishes it from list_tasks and create_task among siblings. The added API route reinforces the exact operation, though it never explicitly names the 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?

No guidance on when to use this versus list_tasks or a filtered lookup, and no prerequisites (e.g. auth, id format) mentioned. The agent must infer that a single-id fetch is the right choice purely from the word 'single'.

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?

readOnlyHint already declares the safe-read profile, and the description adds value beyond that: the concrete endpoint (GET /api/v0/activities), the supported query features (_page/_limit/_fields/_filters/_search), and the return envelope { meta, response }. It doesn't cover rate limits or auth needs, but discloses return shape and capabilities.

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 sentence plus endpoint and return-shape clauses; every phrase carries information and the core purpose is front-loaded. No filler or 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 read-only list tool with fully documented parameters and no output schema, the description supplies the endpoint, supported query modes, and the { meta, response } envelope, which compensates for the missing output schema. Auth and filtering edge cases are not addressed but are not essential for correct invocation.

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

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

Schema description coverage is 100%, so each of the 5 parameters is already fully documented with defaults and syntax. The description merely restates which query features exist without adding format or semantic detail beyond the schema, warranting the baseline 3.

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

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

States a specific verb+resource ('List activities') and enumerates what an activity is (notes, emails, calls, meetings) logged against objects, which clarifies the domain. It does not explicitly differentiate itself from siblings like get_activity or create_activity, but the list scope is clear from the name and text.

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 (listing activities across objects) and mentions the underlying API endpoint, but gives no explicit when-to-use, when-not, or routing to alternatives such as get_activity for a single record or accelo_request for arbitrary calls. Guidance 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?

readOnlyHint=true already declares this a safe read, so the description need not re-establish safety. It does add the API route and the response envelope 'Returns { meta, response }', which is genuinely useful given there is no output schema, but it stops short of describing pagination behavior, meta contents, or rate limits.

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

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

Three short, front-loaded sentences with no filler: purpose first, then endpoint, then capabilities and return shape. Efficient, though the parameter-name list is redundant given 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 read-only list tool with zero required params, full schema coverage, and no output schema, the description covers identity, endpoint, query capabilities and the return envelope. Only minor gaps remain (no mention of filtering by status/owner semantics or of pagination defaults, though those live in the schema).

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

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

Schema description coverage is 100% and each parameter carries its own detailed description (including the _filters example syntax), so the schema does the heavy lifting. The description merely lists the same parameter names, adding no semantic detail 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?

States a specific verb+resource and even disambiguates the domain ('companies (client organizations)'), plus the backing endpoint. It does not, however, differentiate itself from sibling readers like get_company or from list_staff/list_contacts, so an agent must infer the list-vs-single distinction from names alone.

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 mention of _search/_filters hints at how to narrow results, but there is no explicit 'use this to enumerate all companies; use get_company for one' routing, and no exclusions or prerequisites. Adequate but not directive.

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, so safety is covered. The description adds meaningful context beyond that: the upstream endpoint, the supported query surface, and crucially the response envelope shape { meta, response }, which the agent would otherwise not know since 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 fragments, zero filler, and the most important information (what it lists, the endpoint, the query surface, the return shape) is front-loaded. 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 naming the { meta, response } envelope and summarizing pagination/filter support. Combined with 100% schema coverage, an agent has enough to call this correctly, though ordering/pagination defaults could be stated more explicitly.

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 fully documents all five parameters, including filter syntax examples. The description's mention of _page/_limit/_fields/_filters/_search only repeats parameter names without adding format or interaction detail, so the baseline 3 applies.

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

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

States a specific verb and resource ("List contacts (people at companies)") and even names the underlying API call GET /api/v0/contacts. The parenthetical disambiguates the resource nicely, though it doesn't explicitly contrast with get_contact or list_companies beyond the list/get naming 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?

Usage is implied by the verb and the enumerated query capabilities (_page/_limit/_fields/_filters/_search), so the agent can infer this is the bulk-retrieval tool. However, there is no explicit when-to-use guidance, no statement of when to prefer get_contact, and no exclusion conditions.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the upstream endpoint and the response envelope shape ({ meta, response }), which is real context, but it says nothing about auth requirements, rate limits, or what meta contains (total counts, next-page cursors), so the added behavioral depth is modest.

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 purpose, then the endpoint, then the parameter/return facts. No filler. It could be slightly tighter by not repeating the parameter list already in the schema, but it wastes little space.

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 describing returns and does so only as '{ meta, response }' without explaining meta's pagination/count fields. Combined with zero usage routing against get_invoice, it is adequate but leaves the agent to discover envelope details empirically.

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

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

Schema description coverage is 100%, so every parameter is already fully documented in the schema (including defaults, ranges, and the _filters mini-grammar). The description merely restates the parameter family names (_page/_limit/_fields/_filters/_search), adding no syntax or semantics beyond the schema — baseline 3 is appropriate.

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

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

States a specific verb+resource ('List invoices') and pins it to the concrete upstream endpoint GET /api/v0/invoices, so the agent knows it is a list operation over the invoices collection. It does not explicitly distinguish itself from the singular sibling get_invoice, which is the main remaining ambiguity.

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

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

Usage is only implied: the mention of _filters/_search/_page hints at what this tool is good for (paged, filtered, searched enumeration), but there is no explicit when-to-use guidance and no mention of get_invoice as the single-record alternative. An agent can infer the division of labor from the name but not from the text.

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, so safety is covered. The description still earns credit for disclosing the HTTP endpoint and, importantly given there is no output schema, the return envelope { meta, response }, which tells the agent to expect pagination metadata wrapper rather than a bare array.

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 paragraph that front-loads the purpose before the endpoint and parameter list; nothing is padded. It reads as terse API-reference shorthand, but every clause carries information.

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

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

For a zero-required-param read tool with full schema coverage and readOnly annotations, the description supplies the missing pieces: endpoint identity and return shape. Only the absence of guidance on selecting this over get_issue/sibling listers 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%, so every parameter is already documented with defaults, ranges, and filter syntax. The description merely echoes the parameter names (_page/_limit/_fields/_filters/_search) without adding format or interaction detail, 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 ("List issues — support/service tickets"), and the ticket gloss disambiguates the overloaded word "issue." It does not explicitly distinguish itself from singular get_issue or from accelo_request, so it falls short of a 5.

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

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

No when-to-use guidance, no exclusions, and no direction on how it relates to get_issue or other list_* siblings. The description only documents surface mechanics (endpoint and query-string options), leaving the agent to infer when this is the right call.

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, so safety is covered; the description adds useful context beyond that by disclosing the raw GET endpoint and the response envelope shape ({ meta, response }). It does not discuss pagination limits behavior or rate limits, but for a read-only list tool this is solid added 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?

Three short, front-loaded sentences with no filler: identity disambiguation first, then API mapping, then pagination support and return shape. Every clause carries information an agent can use.

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 mitigates that by naming the { meta, response } envelope. With zero required parameters and full schema coverage, nothing essential is missing, though it could say a bit more about what each returned job object 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% and each of the five parameters already has detailed documentation, including filter syntax and ordering examples. The description only enumerates the same parameter names (_page/_limit/_fields/_filters/_search) without adding syntax or semantics, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (jobs), and immediately resolves the terminology trap by clarifying that Accelo "jobs" are projects. It even names the underlying endpoint (GET /api/v0/jobs), so an agent can distinguish it from get_job and the parallel list_* siblings 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?

Usage is implied by the list-vs-get naming convention shared with siblings, but there is no explicit statement of when to prefer this over get_job, accelo_request, or a filtered list. No exclusions 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?

readOnlyHint=true already covers the safety profile, so the description's added value is the concrete transport detail (GET /api/v0/prospects) and the return envelope shape { meta, response } — both genuinely useful for an agent. It stops short of mentioning auth, rate limits, or result-size caps beyond the schema.

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

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

Three short sentences, front-loaded with identity, then endpoint, then capabilities and return shape. Nothing is padded and no sentence is filler for an agent that needs to decide and call.

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, mentioning the { meta, response } envelope is a real contribution, and pagination/field/filter support is disclosed. Only the absence of any auth, limit, or result-count caveat keeps this 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% and every parameter already has a detailed description, so the schema carries the load. The description merely lists the same parameter names with no added syntax or semantics, which is the baseline 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?

States a specific verb and resource ('List prospects') and even defines the domain entity as 'sales opportunities in the pipeline', plus names the underlying endpoint. It does not explicitly route the agent against the singular get_prospect sibling, so it falls just short of the top tier.

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 only enumerates supported query mechanics (_page/_limit/_fields/_filters/_search); it never says when to use this list tool versus get_prospect or the other list_* siblings, and gives no exclusions or scoping advice.

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?

readOnlyHint=true already establishes this is a safe read. The description adds genuinely useful context beyond the annotation: the underlying endpoint (GET /api/v0/staff) and the { meta, response } envelope, which matters since there is no output schema. It omits auth/rate-limit/pagination behavior, so not 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?

Three short, front-loaded sentences with no filler; the endpoint and return shape come after the identity statement. The param-name list is mildly redundant against the schema, keeping it from a 5.

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, disclosing the { meta, response } return envelope is the key piece an agent needs, and it is present. Parameters are fully self-documented in the schema, so nothing critical is missing, though filtering/search interaction guidance would round it 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 description coverage is 100%, so each of the five parameters already carries its own meaning and defaults. The description only repeats the parameter names without adding syntax or interaction detail, so the baseline 3 applies.

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

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

States a clear verb+resource and disambiguates 'staff' as 'Accelo users in your deployment', which separates it from sibling list_contacts/list_companies. It never explicitly routes the agent between list_staff and get_staff, so it falls short of a 5.

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

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

The description says what the tool supports but never says when to use it versus list_* vs get_staff siblings, nor any prerequisite or exclusion. 'Supports _page/_limit/...' is parameter inventory, not usage guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely new behavioral context beyond the annotations: the underlying HTTP verb/path (GET /api/v0/tasks) and the response envelope '{ meta, response }', which matters because no output schema exists. It omits any note on rate limiting, default ordering, or maximum result windows.

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, each earning its place: resource definition first, endpoint second, query/return contract third. No filler, no repetition of the title, and the most important scoping information is front-loaded.

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

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

For a five-parameter, zero-required, read-only list tool with no output schema, the description covers purpose, endpoint, supported query modifiers, and the return envelope. It is close to complete; the remaining gap is that it does not characterize what a task object contains or the default sort/pagination behavior an agent would need to interpret results.

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

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

Schema description coverage is 100%, so every parameter (including the intricate _filters syntax) is already fully documented in the schema. The description only re-enumerates the same five knobs (_page/_limit/_fields/_filters/_search) without adding syntax, defaults, or interaction rules. Baseline 3 is appropriate when the schema does all the work.

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

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

States a specific verb (List) plus resource (tasks) and then disambiguates the resource itself as 'units of work logged against an object such as a job or company,' which prevents confusion with jobs or activities. It also names the concrete endpoint (GET /api/v0/tasks). It stops short of explicitly distinguishing itself from get_task or the create_* siblings, so it is clear but not fully sibling-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 description never says when to use this tool versus get_task (single record) or the sibling list_* tools, nor does it mention prerequisites or when to filter vs. page. It implies bulk retrieval of tasks only through the verb 'List'; no explicit context or exclusions are provided.

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