Accredible MCP by usefulapi

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

readOnlyHint=true already tells the agent this is a safe read, and the description usefully supplements that by disclosing the return payload's breadth (evidence items, references, custom attributes, skills) — valuable given there is no output schema. It does not cover error behavior for an unknown id, but the annotation carries the safety profile.

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

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

Two tight sentences with the resource and its payload front-loaded, no filler. The trailing "GET /v1/credentials/{id}" endpoint notation is mildly redundant for an MCP caller but costs little.

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 one-parameter read-only tool with no output schema, the field enumeration effectively stands in for a return-value description, and the id semantics match the schema. 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 coverage is 100% and the parameter already documents "numeric id or custom credential id (license_id)"; the description restates the same dual-id semantics almost verbatim. Baseline 3 is appropriate since the schema does the heavy lifting and the description adds no format or lookup nuance.

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

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

The description names the resource concretely ("One credential in full") and enumerates exactly which fields come back, so an agent knows this is a single-record retrieval rather than a search. It never explicitly names the sibling it is distinct from (accredible_search_credentials), so sibling differentiation is left to inference.

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

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

Usage is implied by "One credential in full" — a single-record lookup versus the list/search siblings — but there is no explicit when-to-use or when-not-to-use statement, and no mention that a known id is required to call it.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: 'Read-only despite being a POST', which resolves the otherwise confusing HTTP method, and it names the actual endpoint path. Auth and rate-limit behavior remain undisclosed.

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

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

Two sentences, front-loaded with what the tool returns, followed by a short behavioral caveat and the endpoint. Every clause earns its place 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?

For a single-parameter, read-only analytics fetch with full schema coverage and no output schema, the description covers the nature of the return data (timestamped events) and the method caveat. It is nearly complete, missing only pagination or result-size expectations if any.

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

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

Schema description coverage is 100%, and the single id parameter is fully documented in the schema itself (numeric or custom credential id). The description adds no format or semantics 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?

States a specific verb and resource (the analytics events of one credential) and even enumerates the event types (recipient views, shares, privacy changes, verification). The scoping phrase 'of one credential' distinguishes it from the sibling accredible_list_analytics without the agent needing to open either schema.

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

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

The description implies usage by scoping to a single credential, but never says when to prefer it over accredible_list_analytics or what preconditions exist. Usage is inferable from the resource description but not stated explicitly.

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

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

readOnlyHint=true already establishes the safe-read profile, so the description's added value is its state semantics: download links are only present 'once completed,' which tells the agent that fields may be conditionally absent. It does not cover auth or rate limits, but given the annotation coverage 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?

A single front-loaded sentence plus the endpoint route; nothing is wasted. The two-part structure (what you get, then the HTTP path) is easy to scan, though the endpoint string adds little for an agent that only needs the tool name.

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 fields and flags the conditional 'once completed' behavior, which is the main thing an agent needs. The only real gap is the absence of any routing guidance relative to accredible_list_data_exports.

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

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

Schema description coverage is 100% and there is a single parameter, so the schema already carries the load and the description adds no id semantics beyond it. 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?

The description states a specific resource ('One data export') and enumerates the fields it carries (department, status, download links), so an agent knows exactly what it returns. It implicitly distinguishes itself from the sibling accredible_list_data_exports by returning a single export, though it never names that sibling explicitly.

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

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

There is no when-to-use or when-not-to-use guidance, and no alternative tool is named in the description itself (the reference to the list tool lives only in the schema's id description). Usage is only inferable from the fact that the tool requires an id.

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. The description adds the concrete HTTP verb/path, reinforcing the read semantics, and discloses the returned field set, which is useful because no output schema exists. It stops short of covering error behavior (nonexistent id, permissions) or response shape beyond the field 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?

Two compact sentences, field list first and endpoint second, with no filler or redundancy. 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?

With no output schema, the description usefully compensates by naming the returned fields. For a one-parameter read tool with readOnlyHint set, the remaining gaps (when to prefer it over search, failure modes) are modest.

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

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

Schema description coverage is 100% and the single parameter already documents itself, including the hint to use accredible_search_departments. The description adds nothing about the id beyond the path template, 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 resource ('One department') and enumerates the fields it returns (name, description, URL, branding, meta_data), plus the underlying endpoint GET /v1/departments/{department_id}. The singular framing contrasts with the sibling accredible_search_departments, though that alternative is never named.

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

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

The description gives no explicit condition for choosing this over accredible_search_departments; the only routing hint ('accredible_search_departments lists them') lives in the schema's parameter description, not in the tool description. An agent must infer that this is the single-record retrieval counterpart.

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. The description adds that the returned design includes 'its settings' and gives the underlying REST endpoint, but discloses nothing about errors on unknown ids, permissions, or payload shape.

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

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

Two short, front-loaded fragments with no filler; the resource is stated before the endpoint. Slightly telegraphic (no explicit verb phrase), which keeps it just under 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?

For a single-parameter read tool with annotations and no output schema, the bare statement of what is returned is the minimum viable. Since there is no output schema, more detail on what a design object contains would have helped the agent decide whether this call is sufficient.

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

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

Schema description coverage is 100% for the single design_id parameter, so the schema already carries the semantics. The description adds no format, range, or sourcing detail beyond what the schema states.

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

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

Names the resource ('One badge or certificate design') and implies retrieval via the endpoint 'GET /v1/designs/{design_id}'. It contrasts implicitly with the plural search sibling by saying 'One ... design', but never names accredible_search_designs 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?

No when-to-use guidance: it does not say to call this when you already know the design_id versus using accredible_search_designs to find one. The only hint about where an id comes from lives in the schema's parameter text, 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, so the description adds the return-shape enumeration and the HTTP route, which is useful context. It does not cover error behavior, permissions, or whether the response is paginated/embedded.

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

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

Two compact sentences with the resource scope front-loaded ahead of the endpoint detail. The field enumeration is a mild laundry list but every item is informative rather than 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 fields, and annotations carry the safety profile; the single required parameter is fully specified in schema. Only missing element is any note on error/not-found handling or sibling routing.

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% – group_id is fully documented with a pointer to accredible_search_groups. The description adds no additional parameter meaning beyond what the schema supplies, 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+resource ('One group in full') and enumerates the fields returned, plus the underlying REST endpoint. The singular 'One group' implicitly distinguishes it from the sibling accredible_search_groups, though that sibling is not named.

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: the tool fetches a single group by id, and the schema notes that accredible_search_groups lists ids. There is no explicit when-to-use/when-not or named alternative in the description itself.

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

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

readOnlyHint=true already declares the safety profile, so the bar is lower. The description adds value by disclosing the returned field set and that the issuer is scoped to 'the API key' (i.e., implicit credential-bound identity), plus the underlying endpoint GET /v1/issuer/details. It omits auth requirements and rate/credit-consumption behavior.

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

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

Very short and front-loaded with the resource identity, then uses compact fragments for the field list and endpoint. Every clause carries information, though the trailing endpoint fragment is slightly redundant with the tool name.

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 appropriately carries the return-value burden by listing the fields and glossing 'certificate_left' as remaining credential credits. For a zero-param read tool this is nearly complete; it stops short of noting that a valid API key is mandatory (error behavior otherwise).

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

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

Zero parameters, so the baseline is 4 and there is nothing for the description to clarify. It correctly implies no input is needed, consistent with the empty 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?

Names a specific verb+resource ('Get the issuer (account)') and goes further by enumerating what the resource contains (id, name, e-mail, credits, language, URL). It is clearly distinguishable from siblings like accredible_get_credential or accredible_get_design, and even names the backing key the object belongs to.

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?

'Good first call' gives real sequencing guidance — an agent knows this is a sensible bootstrap step before per-resource calls. No alternatives are named, but no sibling retrieves the issuer account, so there is no competing tool to route away from.

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 is consistent with that. It adds genuine behavioral context beyond the annotation: the return payload fields and, more importantly, the key-scope-dependent visibility rule, which tells the agent a department key may legitimately return a subset of members rather than an error.

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

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

Two dense sentences with the returned fields front-loaded and the visibility caveat immediately after; the trailing endpoint reference is mildly extraneous but useful for a developer-facing API tool. No filler or repetition.

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

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

There is no output schema, and the description compensates by enumerating the returned fields. For a single-parameter read tool with clean annotations, nothing critical is missing, though error behavior (e.g. non-existent or out-of-scope id) is left unstated.

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

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

With one parameter at 100% schema description coverage, the schema already documents id as a positive integer team member id. The description adds no format, range, or lookup-hint information beyond that, 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?

Names the exact resource (one team member of the account) and enumerates what is returned — name, e-mail, permissions per department — plus the underlying endpoint GET /v1/team_members/{id}. No sibling in the list retrieves team members, so there is no ambiguity to resolve.

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 explains that visible members depend on the key type (account-wide key sees all, department key only its own department), which is useful scoping context, but it never states when to reach for this tool versus another or any preconditions/exclusions. Usage is only implied by the retrieval verb.

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?

Goes well beyond the destructiveHint=false/readOnlyHint=false annotations: it discloses that drafts consume no credit and send no e-mail, that publishing consumes a credit and the account silently falls back to unpublished when credits are exhausted, that a Dashboard sandbox setting overrides publish, and that repeat calls create duplicate credentials. These are non-obvious side effects and failure modes that annotations cannot express.

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?

Everything is in one dense but front-loaded paragraph that opens with the WRITE marker, cardinality, and target resource before detailing side effects. Every sentence carries operational weight, though the run-on length makes it slightly harder to scan than an ideally chunked definition.

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

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

For a 14-parameter mutation tool with nested objects and no output schema, the description covers the decision-relevant behavior thoroughly (publish semantics, credits, idempotency, scope limits). The main omission is what the call returns, which the agent must infer since no output schema exists.

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 14 parameters, making 3 the floor. The description still adds meaning the schema lacks: the reliable pattern of supplying your own credential_id to make later lookup possible, and the publish/credit/e-mail consequences of the publish parameter rather than just its type.

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 ONE credential (badge or certificate) for ONE recipient in an existing group') and bounds the cardinality explicitly. An agent can distinguish it from the search_/get_ 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?

Explicitly routes behavior: default = unpublished draft (no e-mail, no credit), publish=true = immediate publish with e-mail and credit consumption, plus the sandbox-mode override. It also states what this tool does NOT do (evidence, references, bulk issuing, edits, deletes) and warns about non-idempotency, which is precisely the when-to-use/when-not information an agent 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 real behavioral context beyond that: the event scope is account-wide, results are paged with a default of 100 per page, and the underlying endpoint is GET /v1/analytics. It stops short of describing sort order or what a page boundary looks like.

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

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

Two compact sentences: scope and event types first, then filtering and paging, then the endpoint. No filler, no repetition, and the most decision-relevant fact (account-wide) 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?

Six optional parameters, no required ones, and no output schema, so the description carries some return-value burden. It covers paging, page size, and event scope adequately, though it does not characterize the fields within an analytics event record, which an agent composing a follow-up call might want.

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

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

Schema coverage is 100%, so every parameter (page, page_size, start_date, end_date, group_id, department_id) is already documented in the schema. The description restates the date-range/group/department filters and the page size default but adds no format or edge-case detail beyond the schema. 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 ('credential analytics events') and scopes it as account-wide, with concrete examples of event types (views, shares, downloads). It implicitly distinguishes itself from the credential-scoped sibling accredible_get_credential_analytics via 'Account-wide', but never names that alternative explicitly.

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

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

'Optionally for a date range, group or department' tells the agent what filtering is possible, which implies when the tool applies. There is no statement of when to prefer this over accredible_get_credential_analytics or accredible_get_data_export, and no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; beyond that the description adds real context: results are limited to departments the key can access, exports are created in the Dashboard rather than via API, and status values are enumerated (scheduled, processing, completed, errored). Pagination and result-size behavior are still undisclosed.

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

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

Two compact sentences that front-load the resource and its access scope, then the returned fields and endpoint. Dense and low-waste, though the colon-list phrasing is slightly clipped.

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 documents what a caller gets back (department, status, download links) and enumerates status values, plus the auth scoping constraint. Missing pagination or ordering details keeps it from being fully complete for a list endpoint.

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

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

The tool takes zero parameters, so there is nothing for the description to compensate for; this is the baseline-4 case. The description adds return-field semantics instead, which is useful but not a parameter concern.

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

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

The description names the resource (data exports) and its scope (departments the key can access), and lists the fields returned (department, status, download links), which clearly separates it from the singular accredible_get_data_export sibling. It lacks an explicit verb, but the enumerated content makes the operation 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?

Usage is only implied: the agent can infer this is the listing endpoint for exports, and the note that 'Exports are created in the Accredible Dashboard' signals there is no create counterpart to route to. There is no explicit when-to-use versus accredible_get_data_export or any stated precondition beyond key scope.

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 tell the agent this is a read, and the description goes well beyond that by naming the entitlement failure mode (HTTP 403 plan_not_entitled) and the pagination ceiling of 10 per page. It does not describe request throttling or what an empty/unentitled department returns, so it is not fully exhaustive.

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

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

Three short sentences, front-loaded with what is returned, then the constraint, then pagination, and the trailing 'GET /v1/skill_frameworks' is a compact endpoint hint. Very little waste, though the endpoint string is the least load-bearing element.

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 previews the return shape ('each with its published versions') and covers the entitlement precondition and paging limits. The main omission is the total-count/next-page retrieval note that the schema mentions only on the page parameter.

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 (page, page_size, department_id) are already documented, including defaults and the max of 10. The description's 'Paged, max 10 per page' merely restates the schema's page_size bound rather than adding new 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?

It uses a concrete verb (list) and a precisely scoped resource (skills frameworks enabled for a department, with their published versions), and it names the concrete framework families (O*NET, ESCO, NACE). The scope is clear enough to separate it from search_skills, but the description never explicitly contrasts itself with that sibling, so it stops 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?

It supplies real invocation guidance: the tool is department-scoped, requires a plan that includes skills frameworks (otherwise HTTP 403 plan_not_entitled), and is paged with a max of 10 per page. What it lacks is any explicit statement of when to pick this over the search_skills sibling, so it is clear context without exclusions.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this ("a read-only search"), so the bar is lower. It adds genuinely useful non-obvious context: the endpoint is POST despite being a read, and pagination is cursor-driven via meta.next_page. It does not describe result shape or default/maximum page size behavior, but that is covered by 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?

A single front-loaded sentence plus a paging clause, with no filler. The parenthetical gloss is longer than a bare definition but earns its place by explaining a domain-specific term the agent cannot infer.

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 still names the primary return concept (attribute keys, usable as custom_attributes) and reveals the pagination field (meta.next_page) needed to iterate. Safety is handled by annotations. Only the filter semantics of kind/name/department_id are left entirely to the schema, which is acceptable at 100% coverage.

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 kind, name, page, page_size and department_id with types, ranges and defaults. The description's only parameter-related contribution is restating the page/meta.next_page pattern, which the schema already says. Baseline 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 concrete verb and resource ("List the custom attribute keys") and then defines the resource in-line ("placeholders such as a grade or date that credential designs and e-mails merge in"), which is exactly the disambiguation an agent needs for an unfamiliar domain term. No sibling tool searches attribute keys, so there is no plausible confusion with the other search_* tools in the list.

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

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

Gives a clear reason to call it ("useful to know which custom_attributes a credential can carry") plus an operational instruction for paging ("pass meta.next_page as page"). It does not state when not to use it or name a competing tool, 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 only give readOnlyHint, so the description usefully adds that this is 'a read-only search' despite the POST verb — a non-obvious clarification — and discloses pagination behavior ('pass meta.next_page as page'). It does not describe return shape or result limits beyond what pagination implies.

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

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

Three terse clauses front-load the resource definition, filters, and pagination with no filler. Efficient and well ordered, though the parenthetical definition and endpoint note are tightly packed.

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

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

For a 7-parameter, all-optional search tool with no output schema, the description covers the resource, filterable fields, and the pagination mechanism needed to call it correctly. It could say more about the returned result structure, but the essentials are present.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters, making this the baseline 3. The description's filter list (ids, name substring, public) and pagination note merely restate what the schema provides without adding format or edge-case detail.

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

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

States a specific verb and resource ('List collections') and clarifies what a collection is ('sets of groups shown together'), which disambiguates from the sibling search_groups. It does not explicitly name alternative tools, but no sibling competes for the same resource.

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?

Implicitly frames this as a filtered search with pagination, and there is no sibling collection-search tool to route against, so usage is largely implied rather than stated. No explicit when-to-use or when-not-to-use guidance is 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?

With only readOnlyHint available, the description carries the load well: it notes the operation is a POST that is nonetheless a read-only search (disarming a likely agent misconception), documents the AND filter semantics, the default ordering, the paging ceiling (first 10,000 results), and the cursor/offset mutual exclusion. It also enumerates the returned fields, compensating for the absence of an 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?

A single dense paragraph that is front-loaded with purpose and scope, then behavior (returned fields), then paging mechanics. Every clause earns its place; nothing is restated from the schema verbatim.

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

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

For an 18-parameter, zero-required search tool with no output schema, the description covers the gaps that matter most: what comes back and how to page. Minor omissions remain (e.g., behavior with no filters applied, permissions/auth expectations), but an 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 coverage is 100%, so the baseline is 3, but the description adds genuinely new meaning: filters combine with AND (not stated in schema), the 10,000-result paging ceiling, and that cursor and offset cannot be combined. It stops short of explaining field-specific syntax such as date formats or the group_id/license_id relationship.

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 ('Search issued credentials (badges and certificates)') and scopes it with compound-AND filtering and default ordering. It is clearly distinguishable from accredible_get_credential (singular fetch) and the other accredible_search_* siblings by naming the credential domain and the filter/return surface.

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

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

Gives concrete operating context: filters combine with AND, results are newest first by default, and paging must use either size+offset or cursor. It does not explicitly name when to prefer this over accredible_get_credential or the export tools, so it falls just short of explicit alternatives/exclusions.

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

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

Annotations already declare readOnlyHint=true, but the description adds real behavioral context beyond that: visibility depends on whether the key is account-wide or department-scoped, pagination is driven by meta.next_page, and the underlying call is a read-only POST. These are useful non-obvious traits an agent would not infer from the annotation alone.

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 purpose, followed by scope, pagination and HTTP verb in a compact sequence. Every clause carries information; the parenthetical defining departments is the only slightly verbose element but it earns its place given the domain term.

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 mentions meta.next_page, hinting at the response envelope's pagination field. Combined with annotations covering the safety profile and full schema coverage of parameters, the definition is nearly complete; only an explicit note on the returned department object shape 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 the schema already documents page, page_size and the meta_data key/value matching semantics. The description only restates pagination ('pass meta.next_page as page'), adding nothing new, 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 departments') and immediately defines what a department is ('independent organization units with their own designs, groups and branding'). This scope definition cleanly separates it from the singular accredible_get_department sibling and from the other search_* tools.

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

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

The description tells the agent how results vary by key type ('An account-wide key sees all, a department key only its own'), which implies when results will be partial. However, it never states when to reach for this tool versus accredible_get_department or other search_* siblings, so usage guidance remains implicit rather than explicit.

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, but the description earns credit for resolving the tension between the HTTP verb and the semantics: 'POST /v1/designs/search (a read-only search)' tells the agent this POST does not mutate anything. It does not disclose pagination, result caps, or ordering behavior, which keeps it below a 5.

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

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

One compact sentence front-loads the purpose and filters, followed by a short parenthetical covering the endpoint and read-only nature. No filler, no repetition of the title.

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

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

The tool has no output schema, so the description carries the burden of explaining the return shape, yet it says nothing about pagination, result limits, or ordering — a meaningful gap for a search endpoint. It is adequate for a two-param optional-filter list tool but not complete.

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

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

Schema description coverage is 100%, so both parameters (kind, meta_data) are fully documented in the schema itself, including the key/value matching semantics for meta_data. The description only echoes the parameter names, adding nothing beyond what the schema provides — 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 and resource ('List badge and certificate designs') plus the optional filter axes, and separately names the sibling family it belongs to (search/get designs). An agent can distinguish it from accredible_get_design (single fetch) and the other accredible_search_* tools 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?

'optionally by kind or meta_data' conveys when the filters apply, so the basic usage context is implied. However, it never names the alternative for a single-design lookup (accredible_get_design) or states any exclusion, leaving routing 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?

readOnlyHint=true is already declared, and the description reinforces it with 'a read-only search' plus the POST /v1/issuer/groups/search endpoint, so there is no contradiction. It adds genuine behavioral detail the annotations lack: AND-combination of filters, partial-match semantics, and the pagination contract for continuing a 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?

Four tightly packed sentences, front-loaded with the resource definition before the filter, return, and paging details. Nothing is redundant, though the sentence mixing return fields with the endpoint is slightly overloaded.

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 10 optional parameters, no output schema, and a nested meta_data object, the description compensates well by listing the returned fields (id, name, course name and description, design ids, language, dates) and explaining pagination and filter combination. Coverage is close to complete for an agent 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 the baseline is 3, but the description adds cross-parameter semantics the schema cannot express: filters are ANDed together and name/course_name are partial matches. It also echoes the pagination contract. It does not clarify the date format or meta_data matching beyond what the schema already states.

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 ('Search groups') and goes further by defining what a group is ('an achievement such as a course or qualification that credentials belong to'), which an agent needs since 'group' is ambiguous. Combined with the 'Search' verb versus the sibling accredible_get_group, the agent can distinguish this tool from its nearest neighbor without opening the schema.

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

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

Gives real usage context: filters combine with AND, name and course_name match partially, and paging works by passing meta.next_page as page. It does not, however, name when to prefer this over siblings such as accredible_get_group or accredible_search_collections, so the routing guidance is implied rather than explicit.

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 only readOnlyHint=true in annotations, the description adds real behavioral context: partial and case-insensitive matching, a 2-character minimum, paged results capped at 50 per page, and the underlying endpoint. It does not describe the response shape, but it goes well beyond what the annotation declares.

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 that front-load the scope, then the matching semantics and paging limit, then the endpoint reference. 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 search tool with a fully documented schema and no output schema, the description covers scope, matching rules, and pagination adequately. It could optionally note required API permissions or that an invalid framework/version id yields no results, but nothing essential to 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 coverage is 100%, so baseline is 3, but the description adds meaning the schema does not: query matches either the skill name or the publisher's identifier, matching is partial and case-insensitive, and page_size is capped at 50. It leaves the page/meta.next_page mechanics entirely to the schema.

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

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

The description gives a specific verb+resource with explicit scope: 'Search the skills of one published skills-framework version'. It also names the two search keys (name or publisher identifier) and the backing endpoint, which cleanly separates it from siblings like accredible_list_skill_frameworks or accredible_search_credentials.

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 establishes the required context (a published framework version, identified by framework_id/version_id) and the schema description points back to accredible_list_skill_frameworks for obtaining the id. However, there is no explicit when-not or alternative-tool routing (e.g. what to use instead when you need all skills unfiltered).

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