HDPhotoHub MCP by usefulapi

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

Goes beyond the destructiveHint annotation by disclosing the write semantics, the non-idempotent duplicate-creation behavior, and the underlying endpoint. It does not cover permission/auth requirements for creating a site on behalf of a uid, or what happens with unknown fields, which would have pushed this higher.

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 fragments, front-loaded with the WRITE marker, then the risk note, then the endpoint. No filler sentences and nothing buried mid-paragraph.

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 19-parameter create operation with no output schema and destructiveHint=true, the description covers the action and the duplication risk but omits the return value (e.g., the new site id), any auth/permission expectations, and any field-level guidance. Adequate to invoke, but not complete for a tool of this surface area.

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 description says nothing about any of the 19 parameters beyond implying that a site belongs to 'a user' (the required uid). With only 58% schema coverage, roughly eight fields (zip, beds, baths, city, state, garage, lotsize, yearbuilt) are undocumented in both places, and the description does not compensate.

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

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

States a specific verb and resource ('create a new property site for a user') and pins the underlying operation ('API: POST /site'). Combined with the non-idempotency note, an agent can separate this from hdphotohub_update_site and hdphotohub_list_sites 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?

'WRITE: create a new property site' plus 'a repeat call creates a second site' gives clear context for when this tool is appropriate and warns against retry loops. It stops short of explicitly naming hdphotohub_update_site as the alternative for modifying an existing site, so no explicit exclusion is stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: the result is scoped to the API key's own brand rather than an arbitrary ID, which tells the agent no arguments or lookups are needed. It stops short of noting behavior on invalid/expired keys.

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: the first front-loads the purpose and return fields, the second supplies the underlying endpoint. Nothing is redundant and nothing essential is missing.

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 explicitly names the returned fields (id and name), and the zero-parameter schema needs no further explanation. For a simple read-only identity endpoint, an agent has everything required to call 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The description correctly signals that no input is required by framing the brand as derived from the API key.

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

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

States a specific verb and resource ('Get the business (brand) the API key belongs to') plus the exact return fields (id and name). This clearly separates it from sibling getters like hdphotohub_get_group, hdphotohub_get_site, or hdphotohub_get_user, which retrieve other resources.

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 when to use it by specifying the brand is the one the API key belongs to, which makes the use case (identify the current authenticated account) reasonably clear. However, it never explicitly states when to prefer this over sibling getters or mention prerequisites such as a valid API key.

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 only the HTTP endpoint (GET /group); it says nothing about what a group contains, error behavior for a nonexistent gid, or permissions required, so value beyond annotations is modest.

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

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

Two short sentences, verb and resource front-loaded, with zero filler. Nothing is wasted.

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

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

For a single-parameter read with a fully documented schema, readOnlyHint, and no output schema, this is close to sufficient. The only real gap is that the description never characterizes what a 'group' record is, which the agent must infer from siblings.

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 gid parameter is well documented in the schema, including its source tool. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get one group by id') with the underlying endpoint, so the operation is unambiguous. The singular 'one group' implicitly contrasts with the sibling hdphotohub_list_groups, but that contrast is never made explicit.

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

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

Use is implied by 'by id' and the schema note pointing to hdphotohub_list_groups as the id source, but the routing hint lives in the schema rather than the description. No explicit when-to-use or when-not 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the media type enumeration and the underlying endpoint (GET /media), but says nothing about error behavior for a missing/invalid id or what a returned item 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 verb and resource; nothing wasted. The "API: GET /media" clause is marginally redundant 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 single-parameter read with annotations covering safety, this is minimally adequate. With no output schema, an agent still does not know what fields a media item returns or what happens on a bad id, which the description could have sketched in one clause.

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 `mid` property already documents its provenance ("from hdphotohub_get_site") plus positivity constraints. The description adds nothing beyond "by id", 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 media item... by id") and enumerates the resource types (photo, video, floor plan), which distinguishes it from list_* and update_media siblings. It does not explicitly name an alternative, but the retrieval-by-id semantics are 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?

There is no guidance on when to use this versus any sibling — e.g. how to enumerate ids first, or that update_media is the mutation counterpart. The only routing hint (that ids come from hdphotohub_get_site) 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 tells the agent this is a safe read, so the description need not re-assert that. What it does add is meaningful beyond the annotations: the specific sub-resources returned (tasks, taxes, payments) and the invoice URL, which is the only disclosure of return shape given there is no output schema. It does not mention behavior on a missing/invalid id, which is a minor remaining gap.

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

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

Two short sentences, resource scope front-loaded, then endpoint and payload fields. Nothing is padded and nothing crucial is buried.

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

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

For a single-parameter read tool with annotations covering safety and no output schema, the description gives enough to call it correctly and to know what comes back. Only the failure behavior for an unknown id is unaddressed, a small omission rather than a blocking one.

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 oid parameter is already documented with its provenance (from hdphotohub_list_orders) and a positive-integer constraint. The description's "by id" adds no syntax or format detail beyond that, so this is the baseline-3 case where the schema does the work.

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

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

"Get one order by id" states a specific verb and resource, and the singular scope immediately separates it from the sibling hdphotohub_list_orders. It even enumerates the payload contents (tasks, taxes, payments, invoice URL), so the agent knows what it is retrieving without opening a schema.

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

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

There is no explicit "use this when…" or exclusion statement in the description; usage is only implied by "one order" versus the list sibling. The schema's parameter note ("from hdphotohub_list_orders") does quietly encode the intended two-step workflow, but that guidance lives in the schema rather than 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?

Annotations already declare readOnlyHint=true, so safety is covered; the description adds the valuable context that the response bundles users and media items with download URLs, types, and order — telling an agent the call is a heavy read, not a bare record fetch. It doesn't discuss errors or missing-site behavior.

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

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

Two short clauses, front-loaded with the verb and resource, and the return contents are packed in without wasted words.

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

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

No output schema exists, so the description's enumeration of returned fields (status, purchase state, users, media with download URL/type/order) fills that gap well. Minor incompleteness around error/empty cases, but sufficient to invoke 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% and the single sid parameter is documented in the schema itself, including its provenance from hdphotohub_list_sites. The description adds no additional parameter semantics beyond identifying the resource, 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 ('Get one property site') and enumerates what comes back: status, purchase state, users, media items. Implicitly contrasts with hdphotohub_list_sites (single vs. list) but never names that sibling explicitly, which keeps it from a 5.

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

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

Usage is implied: fetch the full detail of a single site by id. There is no explicit when-to-use / when-not-to-use guidance or named alternative, though the schema hints the sid comes from hdphotohub_list_sites.

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 needn't restate safety. It adds the backend endpoint (GET /user), but omits notable behavior: both parameters are optional in the schema, yet the description implies one is needed, and it never says what happens if neither or both are supplied.

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 the identifier choice stated up front. The trailing 'API: GET /user.' is marginally useful developer context rather than payload, so it's tight but not perfectly waste-free.

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 with annotation coverage and full schema coverage, this is nearly adequate. The remaining gaps are the edge case of zero or two identifiers supplied and the absence of any hint about the returned user shape, which matters since 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 coverage is 100%, so the baseline is 3. The description does add a small amount of meaning by framing uid and email as an either/or choice, which the schema does not express (no oneOf, no required), but it gives no precedence rule when both are passed.

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 user by id or email'), which is clearly distinguishable from hdphotohub_list_users and hdphotohub_upsert_user. It doesn't explicitly name a sibling, but the singular/plural distinction carries the differentiation.

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

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

Usage is only implied: fetch a single user rather than a list. There is no statement of when to prefer this over hdphotohub_list_users, nor any prerequisite or exclusion. 'Pass uid or email' is identifier guidance, not when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the description only needs to add context. It contributes the API endpoint (GET /webhook) but says nothing about error behavior for a missing id, permissions, or pagination-less single-record semantics.

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

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

Two terse sentences with the operation stated first and the endpoint appended as reference data. Nothing extraneous and nothing buried.

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

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

For a one-parameter read tool with full schema coverage and a readOnlyHint, most needs are met. But with no output schema, a brief note on what a webhook record contains (or what a miss returns) would fill the remaining gap.

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

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

Schema description coverage is 100% and the single wid parameter is already documented as "Webhook id (from hdphotohub_list_webhooks)." The description's 'by id' merely restates the schema, so baseline 3 applies.

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

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

States a specific verb and resource ("Get one webhook by id") and includes the underlying API route, so the operation is unambiguous. It doesn't explicitly contrast with hdphotohub_list_webhooks or hdphotohub_list_webhook_events, though the phrase 'by id' implicitly separates it from listing 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?

Usage is only implied: 'by id' suggests a single-record lookup once you have a webhook id, and the schema points at hdphotohub_list_webhooks as the id source. There is no explicit statement of when to prefer this over the list tool or what happens if the id doesn't exist.

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

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

The readOnlyHint annotation already establishes this is a non-destructive read, so the description carries a lower burden. The added value is the underlying endpoint (GET /groups), but nothing is said about result size, pagination, or what happens when the name filter matches nothing.

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

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

One sentence plus an endpoint reference, with the resource gloss front-loaded and zero wasted words. Nothing needs trimming or reordering.

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-optional-param read-only list tool with no output schema and readOnlyHint already covering safety, the description covers purpose, scope, and filtering. A note on whether all groups are returned by default or how results are ordered is the only meaningful gap.

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

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

Schema coverage is 100% and the single parameter is documented as 'Filter by group name.' The description's 'optionally filtered by name' restates rather than extends the schema, adding no match semantics (exact vs. substring). Baseline 3 is appropriate when the schema already does the work.

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

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

States a specific verb and resource ('List groups') and disambiguates the domain by glossing groups as 'brokerages and teams', which an agent could not infer from the name alone. It does not explicitly separate itself from the hdphotohub_get_group sibling, but the List/Get distinction plus the plural resource makes the split readable.

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

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

The phrase 'optionally filtered by name' implies the intended use case (broad enumeration with an optional narrowing filter), so usage is inferable. However, there is no explicit statement about when to prefer this over hdphotohub_get_group, nor any prerequisite or exclusion.

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 bar is lower. The description adds value by saying what an order record carries (totals, balance due, tasks, payments) and giving the underlying endpoint, but it says nothing about result size, ordering, or pagination behavior.

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

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

Three compact sentences: purpose and filtering first, then payload contents, then the endpoint. Nothing is redundant or buried.

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

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

With no output schema, the description usefully enumerates the main fields of an order, and the annotations carry the safety profile. The only real gap is any notion of result volume or pagination for an unfiltered list 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%, with both sid and uid documented as filters. The description confirms they are optional filters on the same fields, which is a marginal addition; baseline 3 applies since 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 ('List orders') plus the scope of optional filtering by site or user, which separates it from the singular hdphotohub_get_order sibling. It doesn't explicitly name that sibling, so differentiation comes from the name rather than the prose.

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

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

The phrase 'optionally for one site or one user' implies when to pass sid/uid versus listing everything, but there is no explicit guidance about when to prefer this over hdphotohub_get_order or list_user_transactions, and no stated 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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds the backing endpoint (GET /sites) but omits whether the three filters combine with AND or OR semantics, whether an empty filter returns everything, and whether results are paginated.

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

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

Two short sentences with the resource and filters front-loaded. The trailing 'API: GET /sites' is marginally useful for endpoint mapping but is close to padding.

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 all params documented and annotations covering safety, this is nearly sufficient. However, with no output schema, the description should hint at the returned shape or pagination/limit behavior, which it does not.

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

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

Schema description coverage is 100%, so each of the three parameters is already documented in the schema. The description paraphrases the same filters without adding semantics such as mutual exclusivity or precedence between uid, email, and address, so baseline 3 applies.

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

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

States a specific verb (List) and resource (property sites), plus the filtering dimensions. It is clearly distinguishable from get_site (single-site retrieval) by the plural resource and filter framing, though it never names a sibling.

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

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

The description implies usage by listing the available filters, but never says when to prefer this over get_site or list_users, nor whether the filters are required or combinable. Usage must be inferred from the schema's optional parameters.

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 signals a safe read; the description adds the underlying GET /users endpoint and that results span both clients and team members, which is useful. It does not cover pagination, ordering, or empty-result behavior, so added value beyond annotations is modest.

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

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

Two compact sentences, with purpose and filter behavior front-loaded and no wasted wording.

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-optional-param read tool with annotations covering safety and no output schema, the definition is nearly sufficient. Only return-shape/pagination hints are absent, a minor gap.

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

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

Schema description coverage is 100%, so both filters are fully documented in the schema. The description only restates that the same two fields are optional filters, adding no format or matching semantics (e.g., partial vs exact) 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 (list) plus the resource (clients and team members/users), and the API endpoint GET /users confirms it. It clearly differs from get_user, though it doesn't explicitly name that sibling as the single-record alternative.

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?

Notes that filtering by email or name is optional, which gives basic usage context. It does not say when to prefer this over get_user or list_user_transactions, nor any 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's added value is the scoping behavior (date range filtering) and the underlying endpoint. It says nothing about pagination, result caps, ordering, or what a 'transaction' contains — meaningful gaps for a list endpoint.

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

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

Two short sentences, front-loaded with the action and scope. The trailing 'API: GET /user/transactions' is mild filler for an MCP caller but is compact enough not to hurt.

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

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

For a simple three-parameter read tool with full schema coverage and a readOnly annotation, the description covers what the tool returns conceptually (a user's transactions, filterable by date). Only pagination/volume behavior is unaddressed, which is a minor gap given 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%, with uid, dateto, and datefrom all documented including the yyyy-mm-dd format and inclusive bounds. The description only restates that the date range is optional, adding essentially nothing beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('List the transactions of a user') plus the optional scope (date range), which is enough to separate it from sibling list_orders / list_users. It doesn't differentiate against siblings explicitly, but no sibling overlaps with transactions, so the residue of ambiguity is small.

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 within a date range' implies the main use case, but there is no explicit when-to-use, no prerequisites, and no named alternative (e.g. get_order for a single transaction). Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered structurally. The description adds real value by disclosing the return content (event types plus payload options) even though no output schema exists, and it names the backing endpoint. It does not describe result shape, ordering, or whether the list is static.

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 is returned; the endpoint reference is a compact second clause. Nothing is padded or repeated.

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

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

For a zero-parameter read-only lookup with no output schema, the description covers what the tool returns and where it comes from. A richer note on the response structure would help an agent consume the result, but nothing needed to call 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?

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. It correctly gives no parameter text and does not mislead about hidden inputs.

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

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

States a specific verb+resource: it lists webhook event *types* and their payload options, which is conceptually distinct from hdphotohub_list_webhooks (existing webhook subscriptions). The distinction is inferable from 'event types', but the description never names the sibling to make the split explicit.

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

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

No statement of when to use this versus hdphotohub_list_webhooks or hdphotohub_get_webhook, and no prerequisites. The natural use case (discovering valid event names before registering a webhook) is left entirely to inference.

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

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

Annotations already declare readOnlyHint=true, and the description adds only the underlying endpoint (GET /webhooks). It says nothing about pagination, result ordering, or whether disabled webhooks are included.

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

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

Two short sentences, front-loaded with the purpose, with no redundant or filler text. It is terse almost to a fault, but nothing needs trimming.

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 no-argument list tool with no output schema, the definition covers the essentials, but an agent cannot tell from it whether results are paginated or how many webhooks to expect. Adding that detail would make it 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?

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline for a no-parameter tool 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?

The description states a specific verb and resource ('List the configured webhooks'), which clearly distinguishes it from the singular sibling hdphotohub_get_webhook. It does not explicitly mention how it differs from hdphotohub_list_webhook_events, leaving that distinction to inference from names.

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

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

There is no guidance on when to use this tool versus alternatives such as get_webhook (single item) or list_webhook_events (related sub-resource). Usage is only implied by the tool name.

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

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

The description adds useful context beyond the annotations by labeling the operation 'WRITE' and naming the PUT endpoint. But it does not explain the effect on media not included in the array, permission requirements, or whether the supplied order replaces all existing ordering.

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

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

Three short sentences, with the write nature and core action front-loaded. The API endpoint is included compactly and every sentence contributes without fluff.

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 write tool with complete schema descriptions and no output schema, the description supplies enough to call it correctly. The main remaining gap is the lack of explanation about whether the ordering is full replacement or partial.

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 both parameters are already documented in the input schema. The description repeats that media ids should be passed in the wanted order but adds no syntax or constraint details 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?

The description states a specific verb and resource: 'set the sort order of the media of a site.' That is clear enough to separate it from metadata-oriented siblings like hdphotohub_update_media, but it does not explicitly name or contrast any sibling.

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

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

It tells the agent to pass media ids in the wanted order, which is usage guidance for invocation. However, it does not say when to use this rather than hdphotohub_update_media, nor does it state any exclusions or prerequisites.

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

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

The 'WRITE:' prefix and the purchase caveat add real behavioral context beyond the idempotentHint annotation. However, it doesn't disclose consequences of archiving (reversibility, effect on live media/orders) or any permission requirements, which matters for a state-mutating endpoint with no destructiveHint.

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

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

Extremely compact and front-loaded, with the write nature, allowed values, and caveat all in the opening words. The trailing API endpoint line is minor but harmless context.

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

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

For a simple two-parameter mutation with no output schema, the description covers the essential points: it's a write, the allowed states, and a key non-goal. Missing only side-effect/permission 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?

The schema documents sid but leaves status undescribed (50% coverage); the description compensates partially by naming the three valid states, but adds no meaning about what each state implies or how transitions behave.

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

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

Starts with a specific verb (set) and resource (site status), enumerates the three target states, and explicitly scopes out purchasing. An agent can distinguish this from hdphotohub_update_site or hdphotohub_create_site 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 caveat 'This does not purchase the site' usefully narrows when this tool applies, but there is no guidance on choosing between this and hdphotohub_update_site, nor any stated prerequisites (e.g. site must already exist, permissions).

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 'WRITE:' marker plus 'API: PUT /media' usefully discloses the mutation semantics that the annotations (only idempotentHint=true) omit. However, with a PUT it is unclear whether omitted fields are cleared or preserved, and there is no mention of required scopes, whether the change is reversible, or what errors occur — gaps that matter for a destructive write with no destructiveHint provided.

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

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

Two terse, front-loaded sentences with zero filler: the write intent and field scope come first, the endpoint second. Nothing could be cut without losing information.

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

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

For a mutation tool with no output schema, no destructive/readOnly annotations, an undisclosed partial-update contract, and 86% of parameters undocumented in the schema, the description is too thin. It never says what is returned, whether absent fields are nulled, or what permissions are needed.

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

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

Schema description coverage is only 14% (just 'Media id.'), so the description carries real weight, and it does name six of the seven parameters. But it renames 'hidden' as 'visibility' and gives no meaning to the two enums (type, branding) or to defaults, leaving the agent to read the schema for anything actionable.

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 pairs a specific verb with a specific resource and enumerates the mutable fields (name, description, type, visibility, highlight, branding), so an agent immediately knows this is the single-item mutation tool. It also prefixed 'WRITE:' to separate it from the get_* and list_* siblings, though it never names a 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?

The scope ('of one media item') implies when the tool applies, but there is no explicit when-to-use guidance, no prerequisites, and no pointer to alternatives such as hdphotohub_set_site_media_order or hdphotohub_get_media for reading. Usage must be inferred from the field list.

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

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

Annotations only provide idempotentHint, so the description carries most of the behavioral burden and does add real value by declaring write semantics and partial-update behavior. It omits permissions needed, whether a field can be cleared (omitted vs. nulled), error behavior when sid doesn't exist, and the response shape.

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

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

Three short, front-loaded clauses with the WRITE marker first and zero filler. The trailing 'API: PUT /site' is mildly redundant but cheap and useful for API parity.

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 20-parameter mutation with no output schema and half the fields undescribed, the description should explain the sid anchor, allowed/ignored fields, and the return behavior. It leaves the majority of the calling surface undocumented.

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?

20 parameters with only 50% schema description coverage; the description contributes nothing about any field. Several params (uid, uid2, zip, beds, city, state, garage, lotsize, yearbuilt, baths) are undocumented in both the schema and the description, so an agent has no guidance on the biggest area of ambiguity.

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 ('update'), resource ('existing property site'), and marks it as a WRITE operation, which cleanly separates it from hdphotohub_create_site and the read siblings like get_site/list_sites. It does not explicitly distinguish itself from hdphotohub_set_site_status, the other site-mutating sibling.

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

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

'Only the fields you pass change' implies when this is appropriate (partial edits) versus a full replace, but no exclusion or alternative is named. An agent must infer that status changes belong to set_site_status and full creation to create_site.

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 description reinforces the write nature and discloses the PUT /user endpoint plus uid/email-based update targeting, which is useful beyond the idempotentHint annotation. However, it does not explain partial-update semantics, field replacement behavior, permission requirements, or side effects of status changes such as 'deleted'.

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 a single tight sentence with the write warning and create/update logic front-loaded. Every clause carries operational meaning with no filler.

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

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

For an 11-parameter mutation tool with no required fields, low schema description coverage, no output schema, and only an idempotentHint annotation, the description is too sparse. It omits critical guidance on which fields are needed for creation versus update, how omitted fields are treated, and what the operation returns.

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

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

Only uid and email get meaningful context through the create/update rules. With 11 parameters and only 18% schema description coverage, the description leaves name, type, status, phone, title, website, firstname, lastname, and gid semantics largely or entirely undocumented.

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 write operation on a specific resource and explains the create-vs-update mode: create with no uid, update with uid or email. This clearly distinguishes it from read siblings like hdphotohub_get_user and hdphotohub_list_users.

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

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

It gives explicit conditions for choosing create versus update: no uid means create, uid or email of an existing user means update. It does not explicitly exclude cases or name alternatives, which keeps it from a 5.

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