Compoid MCP

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

No annotations are provided, and the description does not disclose behavioral details beyond the creation act. It does not mention permissions, idempotency, validation of slug/title, or effects on existing data. With no annotation support, this falls short of the burden to explain side effects.

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 concise sentence with no superfluous wording. It is front-loaded with the action, but given the tool's complexity, brevity alone does not make it well-structured.

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?

Despite having an output schema, the tool has 9 parameters, none described, and no annotations. The description provides only a minimal statement of purpose, leaving significant gaps in parameter understanding and usage context, making it incomplete for reliable 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?

The input schema has 9 parameters with 0% description coverage, and the description does not mention any of them. It does not explain required fields, defaults, or format expectations, so the agent has no additional semantic guidance.

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 clearly states the tool creates a new community on Compoid, using the specific verb 'Create' and resource 'community'. This distinguishes it from sibling tools like Compoid_create_record and Compoid_update_community.

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

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

The description gives no guidance on when to use this tool versus alternatives such as updating an existing community or searching communities. It lacks any context for prerequisites or conditions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that records are submitted for review, may be rejected when thin, that invalid resource_type and subject values cause 400 errors, that resource_type is inferred from MIME type when omitted, and that 'Artificial Intelligence' is always appended as a default subject. It also clarifies the important server-side file path limitation.

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 long but tightly structured with a one-sentence purpose, clear Required/Recommended sections, and dense, high-value bullets. Every line adds operational detail needed to call the tool successfully, and the formatting makes the information easy to scan.

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

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

The description covers purpose, required and recommended fields, validation failure modes, file upload formats, community lookup, and subject vocabulary. Since an output schema exists, return-value documentation is not needed. The only meaningful completeness gap is the undocumented 'references' parameter and the absence of explicit guidance on when to use update instead of create.

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 compensate, and it does so extensively for community_id, file_upload, creators, keywords, resource_type, and subjects, including exact allowed values and error behavior. The only gap is 'references', which is present in the schema but never explained in the description.

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 opens with a specific verb and resource: 'Create a new Compoid record and submit it to a community for review.' This clearly distinguishes it from sibling tools like Compoid_create_community and Compoid_update_record, and the submission context adds useful precision.

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 clearly separates 'Required' from 'Recommended' fields and warns that thin records may be rejected. It also references sibling tools for supporting tasks (Compoid_search_communities for community lookup and Compoid_upload_file for file paths). It does not explicitly state when to prefer Compoid_update_record for existing records, but 'Create a new' makes the primary use case unambiguous.

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 heavily discloses behavioral traits: it is destructive (tombstoned), affects search visibility, requires creator/owner permissions (403), and describes the success/failure responses including error hints. While annotations are absent, the description covers essential behavior well, though it could mention the tombstoned record's visibility in the API vs search results.

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?

Well-structured with introductory sentence, bullet-like sections for critical info, and a concise required parameter note. The formatting and emphasis on IRREVERSIBLE and limitations ensure the agent sees key points quickly without unnecessary verbosity.

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

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

Given the tool's low complexity (single param), descriptive schema, and comprehensive behavioral coverage (permissions, error hints, irreversible nature), the description is complete and sufficient for accurate selection and 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?

Although the schema only provides a name ('work_id') with 0% description coverage, the description fully explains the parameter: it accepts a PID, URL, or OAI, as shown with examples. This adds meaning beyond the schema and is precise.

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 clearly states it deletes a published Compoid recordholistically, using a specific verb ('Delete') and resource ('published Compoid record'). It includes the important nuance of being IRREVERSIBLE and that it applies to published records only, which differentiates it from update or create operations.

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 states when to use: 'clean up test records'. It also explains when not to use (for drafts: must be published first) and describes the alternative (cancelling via review flow). This is clear guidance on context and constraints.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It states the zip archive output but does not explain what happens if files are not open access, whether the tool fails gracefully, or any side effects like file creation at output_path. This is a significant gap for a download operation.

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 concise sentence that front-loads the core action and key condition. There is no redundant information, and every word adds value.

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

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

Given the tool complexity (3 parameters, no annotations) and 0% schema coverage, the description is incomplete. It does not address error handling, output details beyond the zip archive, or the role of output_path. An output schema exists but is not provided, so the description must stand alone and falls short.

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 compensate for parameter documentation. It does not explain the purpose of work_id, filename, or output_path. While 'record files' loosely ties to work_id, without explicit parameter details, an agent cannot correctly invoke the tool.

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 clearly states the tool downloads record files as a zip archive, with a specific condition (open access). The verb 'Download' and resource 'record files' are explicit, and the action is distinct from sibling tools like upload_file or search_records.

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 when needing to download record files, and the 'if available through open access' condition provides context. However, it does not explicitly mention alternatives or when not to use this tool, such as when files are restricted or when using upload_file for the inverse operation.

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?

No annotations are provided, so the description carries the behavioral disclosure burden. It does disclose one important behavior: the optional query is AND-ed on top of the collection's own scope. However, it does not mention auth requirements, rate limits, pagination, or whether results are read-only; some of this is mitigated by the 'get' verb and the existence of an output schema.

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

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

Two sentences carry all the essential information with no filler. The tool's purpose is stated first, immediately followed by the key parameter relationships, making the description easy to parse and act on.

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

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

For a simple collection-scoped read operation with only three parameters and an output schema present, the description is close to complete. It explains the required parameter and query semantics. It stops short of describing pagination or response behavior, but the output schema and schema defaults cover much of the remaining context.

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

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

With 0% schema description coverage, the description adds meaningful semantics to collection_id by identifying it as the numeric ID from Compoid_search_collections, and it explains query's behavior as an AND-ed filter. Limit is not elaborated, but its default value and integer type in the schema provide enough baseline understanding.

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 begins with a specific verb and resource: 'Get the records that belong to a specific Compoid collection.' It also clarifies scope by distinguishing collection-scoped records from a general search, and the mention that query is AND-ed on the collection's own scope further sets it apart from sibling tools like search_records.

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

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

The description gives clear usage context: use this when you already know the collection_id, and it tells the agent exactly where that ID comes from (Compoid_search_collections). It explains how the optional query composes with the collection scope, though it does not explicitly state when not to use it or name alternatives in exclusion terms.

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?

No annotations are provided, and the description is minimal. It only says 'Get detailed information', which implies a read operation but does not disclose return format, error handling, rate limits, or any behavioral traits. For a tool with no annotation coverage, more detail is expected.

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, front-loaded sentence that contains all necessary information without extraneous words. It is efficient and easily parsed.

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

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

The tool is simple (1 parameter), has an output schema to cover return values, and the description clarifies the parameter semantics. It is adequate for a straightforward lookup, though it could mention error cases or validation, but these are not critical given the low 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?

The schema has 1 parameter with no description, and schema coverage is 0%. The description adds meaning by stating the parameter can be a 'Compoid ID or OAI', which clarifies the accepted value. However, it does not elaborate on formats or provide examples, so it only partially compensates for the missing schema descriptions.

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

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

The description clearly states the verb 'Get' and resource 'detailed information about a specific community', with a specific identifier mechanism ('by its Compoid ID or OAI'). It distinguishes from siblings like search_communities and get_record_details by specifying the action and target.

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 the tool is for direct lookup by an identifier, but does not explicitly state when to use this over search_communities or get_record_details. The mention of 'specific community' and identifier hints at use cases, but lacks explicit alternatives 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?

No annotations are provided, so the description carries the full burden. The verb 'Get' suggests a read-only operation, but the description does not explicitly confirm safety, side effects, error behavior, or authentication requirements. It adds no behavioral context beyond the function's name.

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, front-loaded sentence with no redundant words. It states the action, target, and identifier options efficiently.

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

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

The tool is a simple getter with one parameter and an output schema, so the description needn't detail return values. It adequately explains what the tool does and how to identify the target, though it omits potential error conditions or authorization notes.

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%, but the description compensates by explaining that the 'work_id' parameter accepts either a Compoid ID or an OAI. This gives meaning to an otherwise opaque parameter name, though it does not provide format examples or further constraints.

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 clearly states the tool's function: 'Get detailed information about a specific record' and specifies the selection criteria ('by its Compoid ID or OAI'). This distinguishes it from sibling tools like search_records (which lists records) and get_community_details (which targets communities).

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 'specific record' implies this tool is for retrieving details of a single known entity, as opposed to searching. However, there is no explicit guidance on when to use this tool versus alternatives, nor 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?

No annotations exist, so the description carries the behavioral burden, but the tool is a search/list operation and the description adds the key behavioral nuance that an omitted query returns all collections. It does not explicitly disclose read-only status, auth needs, or pagination behavior, leaving some behavior implicit for a tool with no annotation safety net.

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?

Single compact sentence with high-value details: community scope, examples, ID format, and list-all behavior. No filler and the most important information appears first.

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 an output schema present and only one required parameter, the description gives enough to call the tool correctly: the required community identifier format and the optional query behavior are specified. Limit/pagination details and any access constraints are not elaborated, but the schema defaults and output schema cover much of the remaining need.

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%, but the description compensates by explaining that community_id accepts a UUID or slug and that query is optional, with omission meaning 'list all collections'. Limit remains only schema-defaulted with no additional semantics, so the compensation is strong but not complete.

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 the exact operation ('Search for collections') and the scope ('within a Compoid community'), with concrete examples and a list-all mode. This clearly distinguishes it from sibling search_communities/search_records even though they aren't named.

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

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

Gives clear context: collections belong to a community, and omitting query lists all collections, which tells the agent when a broad listing is appropriate. It does not explicitly contrast with search_records/search_communities or state exclusions, but the target resource is unambiguous.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, but it only states 'Search for communities' and provides no details about read-only nature, sorting, pagination, or edge cases. This is essentially no transparency.

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 sentence, which is concise, but it is also under-specified. It does not structure or convey any value beyond the tool name, making it insufficient rather than appropriately concise.

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

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

The tool has six parameters, one required, and an output schema, yet the description provides no context on how to use it, what results look like, or how it relates to other tools. It is severely incomplete for the tool's 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?

The input schema lists six parameters with no descriptions (0% coverage), and the description does not explain any of them. It adds no meaning to query, sort, limit, title, description, or access_status, leaving semantics to be inferred from names alone.

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 clearly identifies the action ('Search') and the resource ('communities'), distinguishing it from sibling tools like search_records or get_community_details. However, it is minimal and does not specify the search scope or criteria, so it falls short of a perfect score.

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. The description does not mention any conditions, prerequisites, or exclusions, leaving the agent without context for selecting this tool over others.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior, but it only states 'Search for records.' It does not mention return format, pagination, search scope (e.g., metadata vs. full-text), permissions, or any side effects.

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, concise sentence that is front-loaded with the verb 'Search' and provides a clear resource list. It contains no unnecessary words 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?

Despite having an output schema (so return values need no explanation), the description is too sparse for a tool with 15 parameters. It fails to mention that you can filter by many fields, or provide any guidance on constructing an effective 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?

The input schema has zero description coverage for its 15 parameters, and the tool description adds no meaning to any of them. It does not explain the query format, how filters like keywords or date_from work, or how parameters interact.

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 clearly states the tool searches for records in Compoid, listing specific content types (images, videos, papers, articles, analysis). It distinguishes from sibling tools like search_communities and get_record_details by focusing on 'records' and the action 'search'.

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 when a search of records is needed, but does not explicitly mention when to prefer this over alternatives or provide exclusions. For example, it does not compare with get_record_details for retrieving a known record.

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

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

No annotations are provided, so the description carries the full burden. It only states 'update' and partial updates, but does not disclose any behavioral traits such as validation, side effects, permissions, or whether the response confirms changes. For a mutation tool this is a significant 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?

The description is extremely concise and front-loaded. Both sentences earn their place, with no waste. However, it may be too terse, missing opportunities to add useful context without bloating length.

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

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

With 10 parameters, no annotations, and no parameter documentation, the description is insufficiently complete for a complex mutation tool. It does not cover field meanings, prerequisites (e.g., community_id existence), or behavior on invalid inputs. Although an output schema exists, the description should still provide more operational context.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning by indicating optional fields are partial updates, but does not explain any individual parameter semantics (e.g., slug uniqueness, visibility options, member_policy values). The description adds minimal value beyond the schema's field names.

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?

Description uses specific verb 'update' with resource 'community on Compoid', clearly distinguishing it from sibling tools like Compoid_create_community and Compoid_update_record. It states exactly what the tool does.

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?

Provides clear guidance on partial updates ('Only supply the fields you want to change'), implying that omitted fields remain unchanged. It does not explicitly compare to create or other update tools, but the context is clear enough for most use cases.

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

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

With no annotations, the description carries the full behavioral burden and does so richly: versioning, review pending, no-op rejection, published-only constraint, resource_type validation with a 400 error, subject limits, and default subject appending are all disclosed.

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 essential versioning behavior, then organized into Required/Optional sections. Every sentence adds value; no filler or repetition of schema titles.

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

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

For a 9-parameter mutation tool with no annotations, this is remarkably complete: it covers input formats, validation, defaults, error cases, and what happens to unchanged fields. An output schema exists, so return-value details are not required.

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 compensate and does: work_id accepted formats, file_upload data URI/path, resource_type allowed values with error detail, subjects cap and default, plus the subtle 'unprovided fields keep current values' semantics that affect every parameter.

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', further clarifying it creates a new version pending review. The 'existing' qualifier distinguishes it from create_record, and 'record' distinguishes it from update_community.

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?

Provides clear context on how to update: pass only changed fields, no-op rejections, and work_id must be a published PID/URL/OAI. It doesn't explicitly name create_record as the alternative for new records, but the 'existing record' constraint implies the when-to-use boundary.

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

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

With no annotations, the description carries the full burden. It discloses the input format (data URI) and the output (server-side path), which is the core behavioral contract. It does not mention errors or limits, but the main behavior is clearly conveyed.

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

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

The description is two sentences, front-loaded with the purpose, and contains no fluff. Every sentence adds value: purpose, input format, and output usage.

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 upload tool with two parameters and an output schema, this description covers purpose, input format, and output usage. It also ties into sibling tools. Missing error handling or limits, but not critical given the tool's simplicity.

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 compensate. It defines the exact format for file_data (data URI), which is critical. Filename is not explained, but the name is self-explanatory and optional.

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 clearly states the tool's function: 'Upload a file to the Compoid MCP server.' It also explains the return value (server-side path) and how it relates to sibling tools, making it distinct from other operations.

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 explicitly explains when to use this tool: to obtain a file_upload path for Compoid_create_record or Compoid_update_record. This provides direct integration guidance and differentiates it from download_files and other siblings.

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