Compoid MCP

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the description owes little on the safety profile. However, it adds nothing beyond them: no authentication/permission requirements, no slug uniqueness constraint, and no notice of the side effects of creating a public community by default.

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 with no waste, which is structurally sound. But it is minimal to the point of under-specification for a 9-parameter mutation tool, so conciseness is not offset by usefulness.

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?

An output schema exists, so return values needn't be described, but for a write tool with 9 parameters and no annotation-level policy detail the description is far too thin. Policy-bearing fields with defaults (visibility=public, member_policy=open, record_policy=open) are never mentioned, leaving an agent unable to predict the effect of calling with only slug and title.

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 describes 0% of its 9 parameters and the description compensates for none of that. Critical semantics are left unexplained: slug format and uniqueness, title vs description, and the meaning/allowed values of visibility, member_policy, record_policy, community_type and curation_policy, all of which default silently.

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 community'), so an agent immediately knows the operation. It does not differentiate from siblings like Compoid_update_community or Compoid_create_record, and 'on Compoid' is filler, but the core purpose is unambiguous.

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

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

There is no when-to-use guidance, no precedence versus Compoid_update_community or the record-creation siblings, and no prerequisites such as whether the community must be on a Compoid instance the caller controls. Usage is only implied by the verb 'create'.

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 cover the generic write/open-world profile; the description goes well beyond by disclosing concrete side effects and failure modes: invalid resource_type or subjects produce 400s, 'Artificial Intelligence' is always appended, records without keywords are hard to discover, and client-local paths are not reachable by the server. That is substantive behavioral context an agent cannot get from the structured fields.

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?

Long, but deliberately structured under Required/Recommended/Optional headings with the action statement front-loaded, and each block maps to a distinct decision the caller must make. A few lines (e.g. repeated discovery warnings) restate the same point, which is the only slack.

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

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

Given 9 parameters, an output schema, and an open-world write operation, the description supplies formats, defaults, validation rules, and error codes — everything needed to invoke it correctly except the undocumented `references` parameter and any explicit auth/token prerequisite. Otherwise complete for this complexity.

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

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

Schema coverage is 0%, so the description carries the full burden and mostly delivers: file_upload formats (data URI vs server path), creators/keywords list semantics, the full resource_type vocabulary with rejection behavior, subjects limit and vocabulary URL, and community_id accepted forms (slug/UUID/home slug) plus the default. The only gap is `references`, which appears in the schema but is never explained.

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

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

Opens with a specific verb+resource ('Create a new Compoid record') and adds the distinctive outcome ('submit it to a community for review'), which cleanly separates it from Compoid_update_record, Compoid_delete_record, and Compoid_create_community. An agent can identify the operation without reading 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?

Explicitly routes to alternatives: use Compoid_upload_file's returned path for file_upload, Compoid_search_communities or the communities URL to pick a community_id, and Compoid_whoami to resolve the default home community when community_id is omitted. It also states when fields are required vs recommended and why thin records fail, leaving nothing 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 destructiveHint=true, but the description adds the substantive details an agent needs: tombstoning rather than hard removal, disappearance from search results, the creator/community-owner authorization requirement with a 403 outcome, and the 204 success signal. It also predicts failure modes with actionable hints.

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

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

Front-loaded with the destructive warning, then structured sub-paragraphs for constraints and parameters. It is longer than the minimum, and the return/error sentence partly duplicates the output schema, but every block carries usable decision 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 destructive, open-world, single-param tool this covers purpose, irreversibility, preconditions, auth requirements, accepted input forms, and success/failure semantics. An agent can invoke it correctly with no further reference.

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 0%, so the description must carry the parameter alone — and it does, enumerating all three accepted identifier formats (PID like '4171t-rc787', full record URL, or OAI) plus the constraint that the target must be published.

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 ('Delete a published Compoid record') and immediately scopes it to the published-only case, which distinguishes it from sibling update/create/delete-adjacent tools. The IRREVERSIBLE tag is front-loaded and 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?

Gives explicit when-to-use ('clean up test records'), an explicit when-not with the alternative path ('drafts have no PID... must be published first (or cancelled via the review flow)'), and names the permission precondition. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so safety is largely covered. The description adds two useful facts beyond them: output is a zip archive, and the operation is limited to open-access records. It says nothing about how existing files at output_path are handled.

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 with no filler. It is appropriately sized, though its brevity is partly under-specification rather than tight editing.

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?

An output schema exists, so return values need not be explained. But for a tool that writes a zip to disk with a default output_path of '/', the description provides no file-collision, overwrite, or size/availability behavior, and the undocumented filename parameter leaves a real 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 0% for all three parameters, so the description carries the full burden — yet it mentions none of them. work_id, filename and output_path are left entirely undefined (no format, no meaning of the default output_path value).

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 ('Download record files in a zip archive') and scopes it to open-access material, so an agent can distinguish it from the sibling upload_file. It stops short of naming any sibling or contrasting scope explicitly, keeping it a clear-but-undifferentiated 4.

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

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

The clause 'if available through open access' is an access constraint, not usage guidance, and gives no signal on when to prefer this over Compoid_get_record_details or the search tools. There are no prerequisites or exclusions 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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral detail — that an optional query is AND-ed on top of the collection's scope — but says nothing about pagination, ordering, or behavior when the collection is empty.

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 tightly written sentences with the core action front-loaded and the parameter guidance following. Every clause earns its place; 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?

An output schema exists so return values need not be described, and annotations cover the safety profile. What remains is a minor gap: the limit/pagination parameter and any result-set size behavior are unexplained.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It documents collection_id (numeric ID sourced from search_collections) and query (AND-ed onto collection scope), but gives no explanation of limit, whose default of 10 is only visible in the schema.

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

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

States a specific verb+resource+scope: records belonging to a specific Compoid collection. The 'belongs to a specific collection' scoping implicitly separates it from the broader Compoid_search_records, but it never names that sibling, so differentiation is left partly to inference.

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

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

It explains where collection_id comes from (Compoid_search_collections), which implies the prerequisite for using this tool. However, it never states when to prefer this over Compoid_search_records or Compoid_get_record_details, and there are no explicit 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the useful fact that the lookup accepts either a Compoid ID or an OAI, but says nothing about auth requirements, behavior when the ID is not found, or result volume.

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

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

A single sentence with zero filler, leading with the verb and resource and closing with the identifier constraint. Nothing is redundant or front-loaded poorly.

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?

An output schema exists, so return values need not be described, and the tool is a simple one-parameter lookup. The remaining gap is minor: no failure behavior or guidance on obtaining a valid ID when the agent does not already have 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 0%, so the schema alone gives no meaning for community_id; the description partially compensates by stating it accepts a Compoid ID or an OAI. It still omits format examples, whether slugs are accepted, and whether OAI is an alias for the same field.

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

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

The description names a specific verb (Get) and resource (detailed information about a community) and states the lookup key (Compoid ID or OAI). This clearly separates it from search_communities, but it never names the sibling explicitly, so sibling differentiation is implied rather than stated.

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

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

Usage is implied: retrieve the details of one known community when you already have its ID or OAI. There is no explicit when-to-use vs. when-not guidance and no routing to alternatives such as Compoid_search_communities for finding an identifier, Compoid_get_record_details for records, or Compoid_update_community for mutation.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds no behavioral context beyond that: no note on authentication, on what happens when the identifier does not resolve, or on whether the open-world lookup hits an external OAI resolver.

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 with no filler. It is appropriately sized for a one-parameter lookup tool, though the 'Compoid ID or OAI' clause is the only substantive content and could have carried one more clarifying detail at no real length cost.

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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. What remains missing is behavior on a non-matching identifier and any hint that the identifier may come from an external (open-world) source, which matters for a lookup tool with 0% parameter documentation.

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 0% and the single parameter 'work_id' carries no title-level explanation, so the description must compensate. It does add meaningful semantics by stating the value may be a Compoid ID or an OAI identifier, but it never maps that onto the 'work_id' field name, leaving ambiguity about the accepted format.

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

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

Specific verb+resource: 'Get detailed information about a specific record'. The 'by its Compoid ID or OAI' clause distinguishes it from the search_records and get_collection_records siblings, which return sets rather than one record. It stops short of naming those siblings explicitly, so it is clear but not fully differentiated.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no routing to alternatives such as Compoid_search_records when the identifier is unknown. The agent must infer that this is the single-record lookup path purely from the word 'specific'.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the useful behavioral fact that omitting query returns the full list, but says nothing about pagination, result counts, or how the default limit=20 behaves.

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 purpose front-loaded and no filler. Every clause (examples, ID format, query omission) carries information the agent can act on.

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

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

An output schema exists, so return values need not be explained, and annotations cover the read-only safety profile. The only real gap is the undocumented limit parameter and pagination behavior, which is minor for a simple read-only search.

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 0% schema description coverage, the description must carry the params, and it does partially: community_id accepts a UUID or slug, and query's omission behavior is stated. It leaves limit (default 20) completely undocumented, so one of three parameters has no semantics anywhere.

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 (Search) and resource (collections) narrowed to a Compoid community, with concrete examples (Publications, Datasets, subject collections). The resource noun distinguishes it from siblings like Compoid_search_communities and Compoid_search_records, though it never names those alternatives directly.

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?

'omit query to list all collections' gives one clear conditional usage path, which is more than an implied context. However, there is no guidance on when to pick this tool over Compoid_search_communities or Compoid_search_records, and no stated 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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that — no note on match semantics, ranking, result volume, or what the search index covers.

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 single sentence is free of padding and front-loaded, but its brevity reflects under-specification rather than economy — it omits everything an agent would need to call the tool well.

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?

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. But for a 6-parameter search tool with zero parameter documentation, the description is far too thin to be 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?

With 6 parameters at 0% schema description coverage, the description carries the full burden of explaining query, limit, sort, title, description, and access_status. It mentions none of them, leaving five optional filters and the required query completely undefined.

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 names a verb ("Search") and a resource ("communities"), so the basic purpose is inferable. However, it is essentially a verbatim restatement of the tool name and offers no distinguishing information against siblings such as Compoid_search_collections, Compoid_search_records, or Compoid_get_community_details.

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 search versus the other search tools, nor on prerequisites, filtering behavior, or when not to use it. The agent must infer routing from the tool name alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing behavioral beyond that: no pagination, no result-count semantics, no note that the default limit is 5, and no indication of what an empty result means.

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 efficient sentence with the verb and resource front-loaded and no filler. It is not padded, but it is also so short that it leaves obvious informational needs unaddressed.

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?

An output schema exists, so return values need not be described. However, for a 15-parameter search tool with zero schema coverage and no usage routing, the description is far too thin: an agent cannot tell how to build a filtered query or when to prefer a sibling search tool.

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

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

Schema description coverage is 0% across 15 parameters, so the schema supplies names only. The description contributes a marginal hint by listing resource kinds, which loosely maps to resource_type/file_type, but it explains nothing about query, sort, date filters, community scoping, access_status, or how the many optional filters combine.

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 ('Search') and resource ('records') and enumerates the record kinds (images, videos, papers, articles, analysis), which distinguishes it from sibling search tools like Compoid_search_collections and Compoid_search_communities. It stops short of explicitly naming those siblings as alternatives.

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

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

There is no when-to-use guidance, no mention of when a different search tool is preferable, and no prerequisites or context. With three search siblings in the toolset, routing is left entirely to inference from 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?

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the agent knows the write is potentially destructive without the description saying so. The description adds the partial-update contract, which is real behavioral value not present in the annotations, but it never explains what makes the call destructive, whether removed or overwritten values are recoverable, or what permissions are required.

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, action first, then the patch-semantics rule; nothing is padded or redundant. It is appropriately sized for the message it chooses to deliver, though that message is deliberately thin.

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?

An output schema exists, so return values need not be described. But with a 10-parameter destructive update and zero schema descriptions, the description should at minimum characterize what the mutable fields control and any value constraints; it omits all of that, leaving the definition incomplete for the complexity of the tool.

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

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

Schema description coverage is 0% across 10 parameters, so the description carries the full burden and does not compensate. Fields like visibility, member_policy, record_policy, curation_policy and community_type have no described meaning or accepted value set (no enums present), leaving an agent to guess at valid inputs for a mutation that is flagged destructive.

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

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

States a clear verb+resource ('Update an existing community') and names the target system, so it is distinguishable from create_community and update_record at a glance. It stops short of explicitly contrasting itself with those siblings, which is the only thing separating 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?

'Only supply the fields you want to change' gives the agent the key usage rule for a partial update, which is genuinely useful. However, there is no guidance on when to prefer this over create_community or update_record, no prerequisites (e.g., ownership/admin rights), and no note on which field combinations are valid together.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false, openWorldHint=true; the description adds substantial context beyond that: updates produce a new version pending review, no-op updates are rejected, invalid resource_type returns 400 'Not a valid value.', and 'Artificial Intelligence' is always appended to subjects. These are non-obvious behavioral traits an agent needs.

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

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

Front-loads the purpose and versioning behavior in the first sentence, then organizes parameters under explicit Required/Optional headings. The long resource_type list is unavoidable enumeration rather than filler, and no sentence is redundant.

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

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

An output schema exists, so return values need not be described. For a 9-parameter mutation tool with zero schema description coverage, the description supplies identifier formats, per-field meaning, validation behavior, defaults, and versioning semantics, leaving no practical gap for correct invocation.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: work_id accepted formats (PID, URL, OAI) and its published-only restriction, file_upload accepted forms (data URI or server path) with a conditional trigger, the complete resource_type enum, and the 5-item cap plus default-append rule for subjects.

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 ('Update an existing Compoid record') and immediately scopes it ('creates a new version, pending review', only published records can be updated). The published-only constraint implicitly separates it from create_record and delete_record without the agent needing to inspect siblings.

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

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

Gives clear when-to-use guidance ('only pass the fields you want to change; unprovided fields keep their current values') and a when-not condition (drafts have no PID, so only published records can be updated). It does not name alternative tools for related tasks (e.g., create_record, delete_record), so it stops short of full routing 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 the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds genuinely useful behavior beyond that: the required data-URI encoding and the fact that a server-side path is returned. It omits size limits, overwrite behavior, and error modes, but the annotation bar is met.

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

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

Three short sentences, front-loaded with the action, then input format, then return value and downstream use. 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?

An output schema exists, yet the description still usefully names what comes back (server-side path). Input format and workflow are covered; only edge-case details such as limits, permissions, and overwrite semantics are missing for a write tool in an open-world server.

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 0%, so the description must carry the burden, and it does for the critical required parameter by spelling out the exact data-URI form (data:<mime>;base64,<data>). The optional 'filename' parameter is never explained, which is the one remaining gap.

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 ('Upload a file to the Compoid MCP server') and immediately clarifies the accepted payload (data URI) and the outcome. It is trivially distinguishable from the sibling Compoid_download_files and from the record-level tools it feeds into.

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 the agent forward: the returned path is meant to be passed as file_upload in Compoid_create_record or Compoid_update_record. That is real workflow guidance, though it does not mention when NOT to upload or any alternatives for attaching images.

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, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds that identity is derived from the 'configured Compoid API token' (implying no auth parameter is needed) and that an output schema exists, but it discloses nothing further about rate limits or failure modes when the token is absent or invalid.

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 with the action first and the returned payload in parentheses. Every clause earns its place; nothing redundant.

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

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

For a zero-argument, read-only identity probe with an output schema and safety annotations, the description covers what is needed: what it does, what it returns, and where the identity comes from. Only minor gaps (behavior with a missing/invalid token) remain, and the output schema handles return-value 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 tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The mention of the 'configured' token usefully signals that the credential is supplied out-of-band rather than via input.

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 ('Identify') and resource ('the user behind the configured Compoid API token'), then enumerates the returned fields (user id, email, home community). No sibling tool overlaps this function, so the purpose is unambiguous without needing explicit 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 strongly implied by the name and description (call it to discover which account the configured token belongs to), but there is no explicit statement of when to use it versus alternatives or any prerequisites. For a trivial zero-arg tool this is adequate, though a phrase like 'use before other calls to confirm the authenticated identity' would raise it.

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