Gripp MCP by usefulapi

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

Annotations only carry destructiveHint: true and a title, so the description usefully adds the WRITE classification and the key non-idempotency behavior (each call creates a duplicate). It is consistent with the annotation rather than contradicting it, but it does not mention permission requirements or what the response contains.

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

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

Two short sentences, front-loaded with the WRITE marker so an agent sees the mutation risk immediately, with the duplicate caveat next. Nothing is 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 six-parameter mutation with no output schema and no return value documentation, the description should state what comes back (e.g. the new contact id) so the agent knows whether the response can be chained. It covers the operation and its duplicate risk but leaves the result shape unexplained.

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

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

Schema coverage is 100%, so all six parameters are already documented, including the cross-reference from company to gripp_list_companies. The description adds only that the contact is attached to a company, which is baseline-level value; 3 is the correct ceiling when the schema carries the 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 names a specific verb and resource — create a contact person on a company — and adds the underlying API operation (contact.create). It is unmistakable from the list_* siblings, though it does not explicitly name an alternative for cases where a contact already exists.

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?

"Creates a new contact each call; a repeat creates a duplicate" gives a clear usage condition and implicitly warns the agent to check existing contacts first. It stops short of naming the alternative (e.g. gripp_list_contacts) or stating prerequisites beyond the company id reference.

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?

While annotations mark it as destructive, the description adds essential behavioral details: how repeated calls are handled (duplicates), and the functional meaning of the 'CONCEPT' status (it keeps the entry editable). This goes beyond simple CRUD descriptions.

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 highly concise and efficiently structured. It front-loads the primary action and separates the functional mechanics (duplicates/status) from the core API reference without wasted language.

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

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

Given the complexity of managing time registration, the description is very complete. It explains the core operation, the potential pitfalls (duplicates), the status system, and the specific Gripp API endpoint, which adds necessary technical context.

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

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

Since the input schema provides 100% coverage with descriptive parameter definitions, the description does not need to elaborate on specific field meanings. It remains at the baseline score, providing high-level process context instead of semantic detail.

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

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

The description starts with a clear 'WRITE' directive and specifies the resource (hours) and context (on a project/task) within the Gripp system. This is unambiguous and clearly differentiates it from the list or create-contact/task 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 tool provides critical usage feedback regarding idempotency: a repeated call with the same parameters will result in a duplicate registration. This helps the agent understand the behavior limits of the tool.

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

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

Annotations supply only destructiveHint=true, so the description carries real weight here and does add non-obvious behavior: this is a write, and it is non-idempotent (each call creates a new task). What is missing is any statement about side effects beyond the task itself (notifications, assignment effects) or required permissions.

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

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

Three short sentences with zero filler, and the most decision-relevant token ('WRITE') is first. The API endpoint reference is compact and does not displace the behaviorally important duplicate note.

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, 2-required create tool with full schema coverage and no output schema, the description covers operation class and idempotency well. The remaining gap is that nothing tells the agent what comes back (e.g., a created task id) or how to reference the new task in a follow-up call.

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

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

Schema description coverage is 100%, so all six parameters including format constraints (yyyy-mm-dd deadline, length limits) are already documented in the schema. The description adds no meaning beyond that, which is the baseline case for fully covered schemas.

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

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

States a specific verb and resource ('create a task in Gripp') and front-loads the operation class with 'WRITE'. It is unambiguously distinguishable from the list-side siblings such as gripp_list_tasks and gripp_get_record without opening the schema.

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

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

The duplicate warning ('a repeat creates a duplicate') is a genuinely useful usage caution against blind retries, but the description never states when to use this tool versus alternatives, nor prerequisites such as resolving company/employee ids via gripp_list_companies/gripp_list_employees (that hint lives only in the schema). Usage is implied rather than guided.

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 is a non-mutating read, so the safety profile is covered by annotations. The description adds only the underlying API call name ('<entity>.getone') and the entity list, which the schema enum already supplies; nothing is said about behavior when an id is missing or whether ids are scoped per entity.

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

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

Two short clauses, front-loaded with the core action and scope. The trailing 'Gripp API: <entity>.getone' is compact but partly redundant with the schema; the entity enumeration also duplicates the enum, though it remains readable.

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 annotations and full schema coverage, the basics are covered. However, there is no output schema, so the description should hint at what a returned record looks like (and that shape varies by entity), and it omits failure behavior for an unknown id.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, including the enum of allowed entities and the constraint that the id is numeric and positive. The description's restatement of the entity list adds no new meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get one Gripp record by its numeric id') and enumerates the entity types, so an agent knows exactly what single object it returns. It does not explicitly name the list siblings it contrasts with, but the 'one record by numeric id' framing implicitly separates it from the gripp_list_* family.

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

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

There is no statement of when to use this versus the gripp_list_* siblings, nor of prerequisites such as calling a list tool first to obtain an id. The only hint of that workflow ('from a gripp_list_* tool') lives in the schema, not the description.

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 as a safe read; the description adds the 250-row page ceiling and the underlying API method (company.get), which is useful context. It does not cover auth requirements, rate limits, or total-result/ pagination behavior beyond the cap.

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 with the action and resource front-loaded and the entity/field scope plus paging limit packed efficiently. No filler, though the attribute list is somewhat incidental to an agent's decision to call it.

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 5 optional params, full schema coverage and a read-only annotation, the description covers purpose, scoping and the paging cap adequately. Only the shape of returned results goes unmentioned, which matters slightly given there is no 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 the schema already documents filters, operators, ordering and paging fully. The description only echoes the filter/paging/ordering capabilities and the 250 max, adding no semantics beyond the schema — 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 companies in Gripp") and clarifies the domain scope by naming what a company is here (customers, suppliers, prospects) plus the key attributes returned. It is distinguishable from siblings like gripp_list_contacts or gripp_list_projects, though it never explicitly contrasts with them.

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

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

"Supports filters, paging (max 250 per call) and ordering" implies how to use it, but there is no explicit when-to-use or when-not-to-use guidance versus the many sibling list tools, and no prerequisites or exclusions are stated.

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

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

The readOnlyHint annotation already establishes this as a safe read operation. The description adds useful details about paging limits (max 250 per call) and ordering support, but does not cover authentication, rate limits, or response metadata.

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

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

The description is two compact sentences with no wasted text. The primary purpose is front-loaded and the supplementary API reference is brief.

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?

It identifies the fields returned by the tool and summarizes filter, paging, and ordering support, which is enough alongside the fully described input schema. It does not explain the response wrapper or pagination metadata, but no output schema exists to carry that detail.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters in detail. The description only reiterates that filters, paging, and ordering are supported, without adding parameter semantics beyond what the schema provides.

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

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

The description states a specific verb and resource ('List contacts in Gripp') and identifies the returned contact fields. It distinguishes this tool from creation tools by name, though it does not explicitly contrast it with other list tools such as gripp_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?

It mentions supported capabilities like filters, paging, and ordering, but gives no explicit guidance on when to use this tool versus gripp_get_record or other list tools. There are no stated 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?

readOnlyHint=true already covers the safety profile, so the description's real added value is the field list (name, e-mail, function, department, role, active flag), which is useful since no output schema exists. However, the 250-per-call cap is already in the schema, and it says nothing about whether a total count is returned or how to know when paging is exhausted.

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 entity and its fields come first, capabilities second. The opening clause mildly duplicates the tool name/title, which is the only wasted 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?

For a read-only list tool with five optional, fully documented parameters and a declared readOnlyHint, the description plus schema is nearly sufficient. The remaining gap is pagination semantics — whether there is a total/has-more indicator and what happens past the 250 cap — which matters for a tool the agent may need to page 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 the schema already documents filters, order_by, direction, max_results and first_result in detail, including operator enums and defaults. The description only restates that filtering/paging/ordering exist, adding no syntax or semantics 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+resource ('List employees in Gripp') and enumerates the returned fields, so the agent knows exactly what entity is being retrieved. It does not contrast itself with siblings like gripp_list_contacts or gripp_list_tasks, but the resource noun is distinct enough to disambiguate.

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, paging and ordering tells the agent this is the bulk-retrieval path for employees, but there is no explicit 'use this when' statement, no exclusions, and no pointer to an alternative for single-record lookup (e.g. gripp_get_record).

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 doesn't need to restate it. It adds real behavioral context beyond the annotations: the 250-row cap per call, that all filters are AND-combined, that custom fields cannot be filtered, and the underlying API endpoint (hour.get) which aids error diagnosis.

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 resource and its fields before capabilities. No filler; the trailing API-endpoint note is marginal but short enough to be tolerable for an API-mirroring 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?

With five optional parameters, no output schema and only a readOnlyHint annotation, the description does the necessary work: it names the returned fields, the page-size ceiling, the AND filter semantics and the ordering defaults. An agent has enough to call it correctly; only cross-tool routing guidance is absent.

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

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

Schema description coverage is 100%, so the schema already documents operator enums, the field-name pattern, value2 for 'between', and default/limit values. The description echoes the 250 max-pages limit and the custom-field restriction but adds no syntax or format detail the schema doesn't already carry.

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 hours in Gripp") and immediately elaborates what a 'hour' is: time registrations with date, amount, employee, task, status and description. That disambiguates it from sibling list tools like gripp_list_tasks or gripp_list_projects without needing to name them.

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

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

The purpose strongly implies when to call it (when you need time registrations), and the mention of filters/paging/ordering suggests refinement strategies. However, there is no explicit guidance on when to prefer it over a sibling list tool, no prerequisite/permission notes, and no pointer to gripp_create_hour or gripp_get_record for adjacent needs.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the Gripp API endpoint (invoiceline.get) and the returned fields, but says nothing about pagination behavior or row limits beyond what the schema states. Adequate but not enriched.

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 and scope; every sentence carries information. The trailing API endpoint reference is minor metadata but cheap and aids traceability.

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 list tool with no output schema, the description names the fields returned, which compensates for the missing output schema. Pagination is covered by the schema, so nothing an agent needs to call it correctly is absent.

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

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

Schema description coverage is 100%, so all three parameters (including defaults for max_results and first_result) are already fully documented in the schema. The description adds only the provenance hint for invoice_id, which is already in the schema text. 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 ('List invoice lines') and enumerates the fields returned (description, amount, price, VAT), scoped to a single invoice id. It doesn't contrast itself with the sibling gripp_list_invoices, but the parameter hint ('from gripp_list_invoices') makes the parent/child relationship inferable.

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?

'Use this to see what an invoice contains' gives a clear triggering condition, and the invoice_id hint routes the agent to gripp_list_invoices first. No explicit when-not guidance or excluded cases, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the bar is lower. The description adds real context beyond that — the 250-row page cap and the exact field set returned — but says nothing about authentication, rate limits, or what happens on an empty result set.

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 waste, front-loaded with the action and resource before the return fields and the paging limit. Nothing is repeated verbatim from structured data.

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 full schema coverage and no output schema, the description covers the action, the returned fields, filtering, paging and ordering. What remains missing is sibling disambiguation, which matters here because invoice_lines sits adjacent in the tool list.

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

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

Schema description coverage is 100% and each parameter is documented in the schema, so baseline would be 3. The description restates the 250 cap and the filter/ordering capability in prose, giving the agent the operative constraint at a glance without opening the schema, which is a modest but genuine addition.

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 invoices in Gripp') and enumerates the returned fields (number, date, status, company, totals, amount paid, open amount), so the agent knows exactly what it gets. It does not explicitly differentiate itself from the closest sibling, gripp_list_invoice_lines, leaving that distinction to inference from the resource 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?

Usage is implied by the name and the mention of filters/paging/ordering, but the description never says when to prefer this over gripp_list_invoice_lines or gripp_get_record, nor any prerequisites. The agent must infer the routing decision.

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 and the description's job is to add operational context. It does note the 250-per-call ceiling, but that is already in the schema; the genuinely new bit is the underlying API call (offer.get) which aids debugging but says nothing about the response envelope or how to page past 250. Adequate but thin for a read-list tool with 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, front-loaded with the resource and what it returns, then capabilities, then the API endpoint. The trailing "Gripp API: offer.get" is developer-facing trivia rather than agent guidance, but it is a minor cost against an otherwise tight structure.

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-only list tool with no output schema, the description does the important remaining work: naming the returned fields so the agent knows the row shape and stating the page-size ceiling. It stops short of explaining pagination behavior (e.g. whether a total count is returned, how to iterate past 250), which is the one genuine 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 filter syntax, operator list, default sort and offset paging are all fully documented in the schema. The description only echoes the max-250 cap and adds no field names, filterable-field hints, or sorting caveats beyond what the schema provides, 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?

Specific verb + resource ("List offers in Gripp") and it usefully disambiguates the domain term by equating offers with quotes and enumerating the fields each row carries (number, name, date, phase, company, totals, acceptance status). It does not explicitly differentiate itself from entity-listing siblings like gripp_list_invoices, but the entity boundary is clear from the 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?

"Supports filters, paging (max 250 per call) and ordering" only implies usage: it tells you the tool is a filtered list but not when to pick it over alternatives or what it cannot do. There is no explicit exclusion, no prerequisite, and no guidance on when a single-record fetch (gripp_get_record) would be more appropriate.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds real context beyond annotations: the underlying Gripp endpoint (project.get) and the 250-row paging cap, plus that archived projects appear in the results. It does not say whether archived records are included by default or what happens past the last page, which matters for a paginated list.

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 resource comes first, then the payload shape, then capabilities and endpoint. The enumerated field list is a slight run-on but earns its place given there is no output schema.

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

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

With no output schema, the field enumeration is the main way the agent learns what a project record looks like, and it is supplied. All five parameters are covered and paging is mentioned; the remaining gap is behavioral detail about archived-project visibility and pagination termination.

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% — filters, operators, order_by, direction, max_results, and first_result are all fully described in the schema, including defaults and the 250 maximum. The description duplicates the row cap but adds no syntax or semantic detail beyond the schema, 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 verb and resource ("List projects in Gripp") and enumerates the returned fields, so an agent knows exactly what comes back. Sibling tools target other resources (contacts, hours, tasks, invoices), so the name alone already differentiates it; no explicit cross-reference is given, but none is really needed.

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 statement of when to use this versus alternatives such as gripp_get_record for a single project or gripp_list_tasks for project-related tasks. The only usage-adjacent content is a capability note (filters, paging, ordering) rather than selection guidance 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, so the safety profile is covered. The description adds real behavioral context beyond that: paging with a 250-per-call cap, ordering support, and the underlying Gripp API method (tag.get). It doesn't describe the returned shape, but with no output schema that is a minor gap.

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

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

Front-loaded with the verb and resource, then the disambiguating scope, then capabilities. Four short sentences with no filler; the API-method sentence is marginal but cheap and helps routing.

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 five parameters are optional and fully documented in the schema, and the description covers the capability envelope (filter, page, order) plus the page-size limit. Nothing critical is missing; only the response shape is unaddressed, and no output schema exists to cover it.

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 field names, operators, defaults and the 250 max are fully documented in the schema. The description only echoes that filters, paging and ordering exist, adding no syntax or semantics beyond it. 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 tags in Gripp') and immediately scopes what tags are — labels applied to companies, contacts, projects and invoices — which distinguishes it from the many sibling gripp_list_* tools that enumerate other entities.

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 purpose: call it to retrieve tags for labeling/selection. But there is no explicit when-to-use or when-not guidance, no mention of alternatives, and no prerequisites. Adequate minimum, clear gaps.

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 tells the agent this is a safe read, so the description only needs to add context. It does add a real constraint ('max 250 per call') and names the underlying endpoint (task.get), which helps troubleshooting, but it says nothing about pagination termination, empty-result behavior, or the cost of wide filters.

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 verb and resource, then return fields, then capabilities. No restatement of the title and 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?

With no output schema, the description usefully enumerates the returned task fields and the paging ceiling, which is what an agent needs to decide whether this tool answers its question. Remaining gaps are minor: no note on total count/continuation behavior when paging past 250 rows.

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%, including operator enums, wildcard syntax, offset semantics and the 250 cap, so the schema carries the burden. The description only restates the categories of parameters generically and adds no syntax or format detail beyond what the schema already declares.

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 tasks in Gripp') and enumerates the fields carried on each task, which pins down the resource against gripp_list_projects, gripp_list_hours and other list siblings. It stops short of explicitly saying how it differs from gripp_get_record for single-task retrieval, but the resource boundary is unambiguous.

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

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

'Supports filters, paging and ordering' implies how to use it for a scoped query, but there is no explicit when-to-use / when-not guidance and no named alternative. An agent can infer this is the bulk-read path for tasks, but nothing steers it toward gripp_get_record or gripp_create_task.

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