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

With no annotations provided, the description carries the burden of disclosing behavior. It explicitly states it writes to the IPT, automaps columns, and refuses duplicate mappings unless allowDuplicate is set, including the consequence of multiplying published records. This is good transparency for a mutation tool, though it doesn't cover auth requirements or return 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?

The description is brief and front-loaded with the core action, followed by key behavioral notes. Every sentence contributes useful information without redundancy.

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

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

Given no annotations and no output schema, the description covers the essential behavior and parameter semantics. It does not mention return values or error handling, but for a mapping operation this is likely adequate. It could be more complete by explicitly distinguishing from ipt_set_mapping, but overall it's solid.

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 25% (only shortname described). The description adds meaning to source and rowType by placing them in the mapping context, and explains allowDuplicate's role. This compensates for the sparse schema, leaving shortname covered by its pattern.

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 action: mapping a source to an extension, with examples of extension types. It distinguishes itself from siblings like ipt_delete_mapping, though it doesn't explicitly contrast with ipt_set_mapping, which might be a related operation.

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 (to map a source) and provides a key condition (refuses duplicates unless allowDuplicate). However, it does not explicitly state when not to use it or mention alternative tools, leaving some usage context implicit.

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 explicitly states the write operation ('writes to the IPT') and adds critical behavior: text files are validated first and refused on problems unless skipValidation. This is significant behavioral context that goes beyond the schema, though it doesn't cover all side-effects (e.g., whether it replaces an existing source).

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 paragraph that immediately states the operation and lists supported types. The validation detail and skipValidation exception are added without verbosity, making it both concise and informative.

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 7 parameters, 2 required, no output schema, and no annotations, the description adequately covers the core purpose, types, and a key behavioral nuance (validation). However, it doesn't explain the return value or error cases, which would be helpful for a mutation 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 coverage is 71%, so the description compensates by clarifying the type-specific parameters (path for file, url for URL, name for SQL) and the validation behavior. It adds meaning for skipValidation and delimiter, and clarifies type usage, going beyond the bare 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 ('Add') and resource ('data source'), and enumerates the supported types (file, URL, SQL). It clearly distinguishes from siblings by focusing on source creation rather than metadata, deletion, or validation.

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 indicates the tool is for adding sources and implies use cases (local file, URL, SQL), but doesn't explicitly contrast with siblings like ipt_configure_source, which might be used for existing sources. Still, the context is clear enough for an agent to know when to call this tool.

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

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

The description explicitly flags that the tool writes to the IPT and triggers re-analysis, which is useful behavioral context. However, with no annotations at all, it leaves details like whether existing analysis is overwritten, required permissions, and response behavior unstated.

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 dense sentence that front-loads the write side effect, states the core action and relevant fields, then adds the important SQL-source branch. No wasted words, though the density makes it slightly harder to parse.

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 10 parameters, 20% schema coverage, no annotations, and no output schema, the description is too brief to fully prepare an agent to call the tool correctly. It omits parameter-level details, return behavior, and side effects on existing parsed data.

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 20%, so the description must compensate; it successfully maps several prose terms to parameters (delimiter, quote character -> enclosedBy, header lines, encoding, dateFormat) and explains the `fields` parameter for SQL sources. Still, it leaves shortname, source, analyze, and multiValueDelimiter largely unexplained.

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 a specific action and resource: configuring how an existing source is parsed, with concrete attributes (delimiter, quote character, header lines, encoding, date format). It distinguishes itself from source-creation or validation tools, though it does not explicitly name 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?

There is no guidance on when to use this tool versus alternatives like ipt_add_source, ipt_peek_source, or ipt_validate_resource. The only usage hint is the SQL-specific branch ('for SQL sources pass raw fields'), which is useful but does not establish the broader selection criteria.

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 of behavioral disclosure. It explicitly says 'writes to the IPT', which signals mutation, but it does not disclose auth requirements, reversibility, side effects (e.g., whether the resource is immediately accessible), or what happens on import.

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 state-changing prefix '[writes to the IPT]' and a clear, specific purpose. No filler or redundant detail, achieving maximum information density.

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 annotations, no output schema, and only 67% schema coverage, the description is too sparse. It does not address return values, error cases, permissions, or the import behavior (e.g., validation, mapping), leaving an agent with significant gaps for safe and 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 67%, and the schema already documents shortname and dwcaPath. The description adds useful semantics by implying dwcaPath is optional ('empty or importing'), but it does not explain the type enum or shortname constraints beyond what the schema provides.

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

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

The description clearly states the action ('Create a resource') and adds meaningful specifics: empty or importing a Darwin Core Archive from a local path. This distinguishes it from sibling tools like ipt_delete_resource or ipt_add_source, which deal with different objects/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?

There is no guidance on when to use this tool versus alternatives, nor any mention of prerequisites or exclusions. The description simply states what the tool does, leaving the agent to infer usage from the tool name and context.

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 must disclose behavioral traits. It only says '[writes to the IPT]' implying mutation, but it fails to mention that the operation is destructive, irreversible, or that the 'confirm' parameter must be true. Critical safety context is missing.

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 terse, which is concise, but it omits essential details like the confirmation requirement and parameter roles. It's under-specified for a destructive operation, so conciseness trades off necessary completeness.

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 tool with no annotations and no output schema, the description is grossly incomplete. It doesn't mention the confirm gate, required parameters, or any side effects, leaving an agent unable to safely invoke it.

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

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

The description adds no information about parameters. Schema coverage is only 50% (confirm and shortname have descriptions), but the description doesn't compensate for the undocumented mid and rowType. The confirm flag's role is only in the schema, not reinforced 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 states a specific verb ('Delete') and resource ('mapping'), which clearly distinguishes it from sibling tools like delete_resource or delete_source. However, it doesn't elaborate on what a mapping is in this IPT context, so it's clear but minimal.

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 guidance on when to use this tool versus alternatives such as delete_resource or set_mapping. It doesn't mention prerequisites, safe conditions, or scenarios where deletion should be avoided.

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. It does state that the operation '[writes to the IPT]' (indicating a mutation) and limits scope to the IPT. However, it does not disclose the irreversible nature of deletion, potential cascading effects on associated data (mappings, sources), or that confirmation is required. The schema covers the confirm flag, but the description lacks explicit behavioral depth for a destructive action.

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, tightly worded sentence. The '[writes to the IPT]' prefix is front-loaded and immediately signals a mutating operation, followed by the core action and scope. Every word earns its place; there is zero redundancy.

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

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

For a simple two-parameter deletion tool with no output schema, the description covers the essential 'what' and 'where' (IPT vs GBIF). It does not mention irreversibility or that the confirm parameter must be true, but those are partially covered in the schema. Given the tool's low complexity and the schema's completeness, the description is largely sufficient, though a note on the destructive side effects would elevate it.

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

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

The input schema fully describes both parameters: shortname (with pattern) and confirm (with description 'Must be true to actually perform this action'). Since schema description coverage is 100%, the description adds no extra parameter meaning; it merely confirms the action context. Baseline 3 is appropriate because 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?

The description states a specific verb ('Delete'), a clear resource ('resource from the IPT'), and adds a crucial scope qualifier ('never touches the GBIF registry'). This distinguishes it from sibling tools like ipt_delete_source, which targets a different entity (a source). The action and target 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?

The description provides clear context by explicitly scoping the operation to the IPT and excluding any GBIF registry interaction. This implicitly tells the agent when to use this tool (when deleting a resource from IPT) versus when not (if GBIF registry changes are needed). However, it does not explicitly name alternatives or edge cases, so it falls short of an explicit when/not 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?

With no annotations, the description carries the behavioral burden. It does disclose that the operation writes to the IPT and that mappings are a prerequisite, but it does not state that deletion is destructive, irreversible, gated by confirm, or what happens to related data. Partial disclosure only.

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 short sentence with a front-loaded write indicator and a meaningful precondition. Every clause earns its place; there is no repetition of schema data or 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 a simple three-parameter mutation, the description plus schema is arguably callable: required params are present and confirm's gate is documented in the schema. However, with no annotations and no output schema, the description omits the destructive/permanent nature and any guidance on invalid states, leaving meaningful gaps.

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 67%, and the schema already describes confirm and shortname. The description adds no parameter-specific meaning beyond identifying 'a source' as the deletion target, leaving the source parameter's semantics to be inferred from the tool name. Acceptable but not compensatory.

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

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

The description names the verb ('Delete'), the resource ('a source'), and adds the key constraint that mappings must be removed first. It is clear, though it does not explicitly distinguish itself from sibling tools like ipt_delete_mapping or ipt_delete_resource beyond the resource type.

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 parenthetical gives an important precondition—mappings must already be removed—which implies ordering relative to ipt_delete_mapping, but it never states when this tool should be selected over alternative deletion tools. Usage context is implied rather than explicit.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the result (the draft EML) without mentioning whether the operation is read-only, what happens if no draft exists, error handling, permissions, or the response format. This is minimal disclosure for a tool with no safety 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?

The description is a single short sentence with no filler, which is appropriately concise. It front-loads the core information (draft EML) and avoids redundancy. However, it is terse to the point of being vague, so it loses one point for structure that could be more action-oriented.

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 getter with one parameter and no output schema, the description states the core return value (draft EML) but lacks context about the response format, potential errors, or how this differs from other metadata endpoints. It is minimally sufficient but incomplete for an agent to fully understand the tool's behavior without additional inference.

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% (the single parameter 'shortname' has a pattern and description), so the baseline is 3. The tool description adds no additional meaning to the parameter—it does not explain how the shortname relates to the resource or any constraints beyond the schema. Staying at baseline is appropriate.

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

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

The description is a noun phrase stating what the IPT holds, but it lacks an explicit verb like 'retrieve' or 'get'. The tool name implies a get operation, but the description itself does not clearly state the action. It identifies the resource as 'draft EML' which is specific, but it does not differentiate from sibling get_* tools (e.g., ipt_get_metadata, ipt_get_status) beyond the resource type.

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 provides no guidance on when to use this tool versus alternatives. It does not mention conditions under which a draft EML exists, nor does it contrast with related getters like ipt_get_metadata or ipt_get_publication_status. The agent is left to infer usage from the 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?

With no annotations provided, the description carries the full burden. It does disclose the output content in depth and reveals a behavioral branch ('unless all=true'), which is useful. However, it never explicitly states the operation is read-only, notes any prerequisite state of the resource, or hints at permission requirements – moderate transparency for a show-style tool.

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, well-structured sentence that leads with the action 'Show a mapping:' before enumerating the returned components. It is informative without padding, and every clause adds content about what the mapping view contains.

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 there is no output schema and no annotations, the description bears more responsibility. It thoroughly specifies the returned content but leaves the mid parameter unexplained and the all toggle only partially defined. For a tool with 4 parameters and 2 required, this is adequate but has clear gaps that an agent must guess around.

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 50% (shortname and rowType documented; all and mid not). The description partially compensates by explaining the all=true behavior, but the 'mid' parameter (integer, default 0) is never mentioned – an agent cannot tell what mid selects. Since the description covers only one of the two undocumented parameters, it adds value but does not fully bridge the schema 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?

The description gives a specific verb and resource – 'Show a mapping' – and enumerates the displayed contents in detail (source columns, ID column, term assignments, unmapped source columns, unmapped required terms). It is clearly a read/inspection tool distinct from the mutation siblings (ipt_add_mapping/set_mapping/delete_mapping), though it does not name 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?

There is no guidance on when to call this tool versus the mapping-mutation or metadata siblings. It does not state a use case, prerequisites (e.g., a draft resource that must exist), or when one would prefer ipt_get_metadata or ipt_get_status instead. The usage context is left entirely to the agent's 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It clearly states the operation is a read/fetch and describes the output summary, which is helpful. However, it does not disclose potential errors (e.g., if the dataset is not published), authentication requirements, or rate limits, which would be valuable for a metadata-fetching tool.

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, efficient sentence that front-loads the action and resource, then lists the summary fields. Every word earns its place with no redundancy.

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

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

For a simple one-parameter fetch tool, the description is mostly complete: it states the action, the resource, and the return summary. However, it lacks explicit guidance on error cases (e.g., unpublished dataset) and does not clarify the relationship to sibling tools like ipt_get_draft_eml, which would help an agent choose correctly.

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

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

Schema description coverage is 100%, so the schema already documents the 'shortname' parameter. The description adds context that the shortname refers to a published dataset, but it does not add format details beyond the schema's pattern. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Fetch') and resource ('a published dataset's EML') and lists the summary fields returned. It is clear about what the tool does, though it does not explicitly differentiate it from sibling tools like ipt_get_draft_eml or ipt_get_metadata_form, which are related but distinct.

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 for published datasets by specifying 'published dataset's EML', which hints at when to use it versus draft EML tools. However, it does not explicitly state when not to use it or name alternatives, leaving some inference to the agent.

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' and the phrase 'editable fields' imply a read-only operation, but this is not explicitly stated. The description does not disclose error behavior, response format, or any side effects. It adds some context (returns names and current values) but lacks explicit safety guarantees, which is a notable gap given zero annotation coverage.

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 that front-loads the core purpose before the list of sections. The section list is long but necessary and appropriately placed. There is no filler or repetition. It could be slightly more compact by grouping sections, but it is efficient for the information conveyed.

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 tool with two simple parameters and no output schema, the description gives a high-level idea of the return (editable fields with names and current values) but does not specify the structure (e.g., array vs. object, nesting). The list of sections is helpful, but the lack of a precise return format and any mention of error conditions leaves some ambiguity. It is adequate for basic use but could be more 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 schema only describes the shortname parameter (50% coverage). The description compensates for the section parameter by listing all valid values (basic, contacts, etc.), which is not present in the schema. This provides actionable guidance for the section parameter. The shortname is already described in the schema, so no duplication is needed. The added list makes the parameter semantics strong.

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 action (get editable fields) on a specific resource (metadata section) and names the companion tool (ipt_set_metadata_fields). It also enumerates all valid sections, which distinguishes it from siblings like ipt_get_metadata (full metadata retrieval) and ipt_get_draft_eml. This is unambiguous and 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?

The phrase 'to use with ipt_set_metadata_fields' clearly indicates this is a preparatory step for editing metadata, implying it should be used when the agent needs to know editable fields before setting them. It does not explicitly state when not to use it, but the purpose is clear enough to route the agent correctly. A brief contrast with ipt_get_metadata would push it to 5.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It states what information is returned but does not explicitly say the operation is read-only, mention permission requirements, or describe behavior when no publication exists. This leaves side effects and safety assumptions unclear.

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, tightly worded sentence with no filler or redundancy. It front-loads the core purpose and is easy to scan, making it efficient for an agent to parse.

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 absence of an output schema and annotations, the description is too terse to fully equip an agent. It does not specify the log output format, how 'latest publication' is determined, or how logLines changes the response. An agent would need to infer significant detail from the parameter schema and tool name.

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 50% (shortname is described, logLines is not). The phrase 'tail of the publication log' hints that logLines controls the number of lines, but the description does not explain shortname's role or explicitly map parameters. It only partially compensates for the schema 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?

The description clearly identifies the resource ('publication') and what is returned (status with enumerated states and a log tail). It uses domain-specific wording that helps distinguish it from generic siblings like ipt_get_status, though it could be more explicit about its exclusive scope.

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 ipt_get_status or ipt_publish. The description is purely declarative and gives no context on prerequisites, when it is appropriate, or when another tool would be better.

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 bears the full burden of behavioral disclosure. It only states that the tool relates to a publication options form; it says nothing about side effects, return shape, required resource state, or permissions. The name suggests a read-only operation, but the description itself does not confirm that.

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 compact and front-loaded, with no filler or redundant phrases. The key parameter, page, is highlighted effectively, though the overall terseness borders on under-specification.

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 tool with no annotations and no output schema, the description should clarify what the tool returns and when each page value should be used. It does neither, and the large number of closely related sibling tools raises the bar for context that this description fails to meet.

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 50%, so the description should compensate for the undocumented page parameter. It only restates the page enum values that are already present in the schema and does not explain what 'auto-publish' versus 'publication-settings' actually means or how shortname selects the resource.

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 identifies a specific resource ('publication options form') and lists the page parameter values, so it is not a tautology. However, it is a noun phrase with no verb and never explicitly states that the tool retrieves settings, leaving the action to be inferred from the tool name. It partially distinguishes from siblings like ipt_get_publication_status but not clearly from other getter-style 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?

There is no guidance on when to use this tool versus alternatives such as ipt_set_settings, ipt_get_publication_status, or ipt_get_metadata_form. The parenthetical page values hint at two modes but provide no selection criteria 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?

With no annotations provided, the description carries the behavioral disclosure burden. It provides useful context by listing what the status report contains, which helps an agent anticipate the response. However, it does not explicitly state read-only behavior, error handling for nonexistent resources, or authentication prerequisites.

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, dense sentence that front-loads the core purpose ('Status of a resource') and then list the key report categories. Every part earns its place, with 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?

For a simple single-parameter getter with no output schema, the description covers the main dimensions of the status response. It is arguably missing a few format details about how 'problems' or 'published/next version' are represented, but it provides enough for an agent to select and invoke the tool confidently.

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 'shortname' parameter is already documented in the schema with a pattern and description. The tool description adds no extra parameter-level meaning, so the baseline score of 3 applies.

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

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

The description clearly states the resource and enumerates the exact facets reported: visibility, sources, mappings, metadata validity, problems, and publication versions. It is easy to tell this is a status/getter tool, though it does not explicitly differentiate itself from closely related siblings such as ipt_get_publication_status or ipt_get_mapping.

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: call this when you need an overall status summary of a resource. However, it gives no explicit guidance on when to prefer this over siblings like ipt_validate_resource or ipt_get_publication_status, nor any exclusions for more targeted checks.

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 burden. It discloses that the tool is public and reports disk/registry/network flags, which is useful. However, it doesn't describe what the response contains beyond those flags, or any side effects (likely none).

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 short sentence with no waste. The key qualifiers (status scope and public access) are front-loaded.

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

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

For a zero-parameter public status tool, the description is nearly complete. It could mention the return format or how it differs from ipt_get_status, but the simplicity of the tool lowers the bar.

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 has zero parameters, so the schema is trivially complete. The description adds context about what the status covers (disk, registry/network flags), which is meaningful despite no params.

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 ('status') and resource ('IPT'), and clarifies it covers disk, registry/network flags. It distinguishes from siblings like ipt_get_status by noting it's public, though it doesn't explicitly name the sibling it differs from.

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 this is a lightweight public health check, but doesn't explicitly state when to use it vs ipt_get_status or other status-related tools. The 'Public' qualifier gives some context but no explicit exclusions or alternatives.

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 explains that private resources are excluded, clarifies that a records value of 0 reflects the inventory's lack of a count rather than an empty dataset, and details the side effect of searchMetadata (fetches EML). These are meaningful behavioral traits beyond the basic 'list' 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 compact and front-loaded: the core action and returned fields come first, followed by scope and behavioral nuances. Every sentence adds value (visibility, query behavior, records interpretation), with no redundancy or 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 a list tool with no output schema, the description lists the return fields and addresses key edge cases. It does not mention pagination behavior, ordering, or error conditions, but these are minor and partially covered by the `limit` parameter schema. Overall, it provides enough for an agent to call and interpret results 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 schema covers 67% of parameters with descriptions, but the tool description adds significant meaning: it explains that `query` matches id and title, and with `searchMetadata` also searches abstract and keywords. This enriches the semantics beyond the schema, while `limit` is well-specified by min/max/default 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?

The description states a specific verb ('List'), resource ('published datasets of the IPT'), and enumerates the returned fields (id, title, version, records, core, DwC-A/EML URLs). It also distinguishes from siblings by specifying 'published' and 'IPT', which separates it from ipt_list_instances and ipt_list_managed_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 provides clear context on what is listed (public datasets only) and how query and searchMetadata behave, but does not explicitly name alternatives or give when-not-to-use guidance. The 'Public: private resources do not appear' clause is a conditional, but no sibling tools are referenced or contrasted.

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 must disclose behavior. It does not state whether this is a read-only operation, whether it requires authentication, or how it handles errors. It does not reveal any side effects or limitations. For a listing tool, this is a significant gap in behavioral 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 concise sentence that is front-loaded with the core purpose. It avoids unnecessary verbosity, earning high marks for efficiency, though it could have added more context without becoming verbose.

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 resource listing tool with one parameter and no output schema, the description is minimal but lacks important context such as authentication, response format, or error handling. The absence of annotations places the burden on the description, which it fails to meet. More detail is needed for an agent to invoke it correctly in a workflow.

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 does not add meaning beyond the schema, but the schema covers 100% of the parameter (shortname) and provides a clear description and pattern. Therefore, the description adds no additional value, but baseline of 3 is appropriate given high schema coverage.

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 it lists extension row types available for mapping on a resource, which is specific enough to indicate what it does. However, it does not differentiate it from sibling tools like ipt_list_managed_resources or ipt_list_instances. It mentions 'mapping' which hints at a connection to mapping tools, but no explicit contrast.

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 does not provide guidance on when to use this tool versus alternatives. No context on typical use cases, prerequisites, or whether it is a read-only operation. It is merely a statement of what it returns, leaving the agent to infer when it should be called.

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 provides a useful behavioral caveat: 'Never shows credentials.' With no annotations present, this partially fulfills the transparency burden, but the description does not clarify side effects, potential errors, or the exact output format beyond the parenthetical field list.

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

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

A single focused sentence conveys the tool's purpose, the relevant fields, and an important security constraint without filler. Every phrase earns its place.

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 list operation, the description covers the resource, the returned fields, and the credential-exclusion behavior. It is sufficiently complete, though it does not explicitly state that the result is a list/array or describe empty or error cases.

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 has zero parameters, so schema and description have no parameter semantics to clarify. The description instead explains what the returned entries contain, which is more than the empty schema alone provides.

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

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

The description clearly identifies the resource as the IPT servers this MCP can talk to and enumerates the returned fields (name, URL, default, credentials presence, read-only). It is distinguishable from sibling list tools like list_datasets and list_managed_resources, though it does not explicitly name or contrast those siblings.

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

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

The use case is implied: an agent would call this to discover which IPT servers are available and their basic properties. However, the text does not explicitly state when to prefer this over alternatives or mention any exclusions, and sibling differentiation must be inferred 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?

With no annotations, the description carries the burden of behavioral disclosure. It does disclose the credential requirement, which is useful signal about the tool's environment dependency)Skip. It does not describe the return format, whether the call has side effects, or what happens if credentials are missing, but for a simple listing operation the prerequisite disclosure provides moderate 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, direct sentence that includes the core purpose and the necessary prerequisite. There is no redundancy or filler, and the most important qualifier ('Resources the configured IPT user can manage') 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?

For a no-parameter, no-output-schema list utility, the description is largely complete: it states the subject, the user scope, and the required credentials. It falls slightly short of perfection because it does not explicitly say that the output is a list of resource identifiers or descriptions, but that is reasonably inferable from 'Resources.'

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 has zero parameters and the schema coverage is 100%, so the description needs to add no parameter-level meaning. The statement about the configured IPT user and credential requirement slightly enriches the context around those implicit settings, but mostly the schema is 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?

The description states what the tool provides: 'Resources the configured IPT user can manage.' This is clear enough to understand the tool lists/manages the resource set tied to the IPT user, and the name 'list_managed_resources' reinforces the action. It doesn't explicitly contrast with siblings like ipt_list_instances or ipt_list_datasets, but the 'can manage' qualifier distinguishes this from generic instance/dataset lists.

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 – when you need to know what the configured IPT user can manage – and it highlights a concrete prerequisite: 'needs IPT_EMAIL/IPT_PASSWORD.' However, it does not explicitly state when not to use it or name any sibling alternative such as ipt_list_instances or ipt_list_datasets. Usage context is present but 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?

No annotations are provided, so the description carries the full burden. It implies a read-only preview operation but does not disclose behavior such as whether it parses the entire file, how many rows are returned, whether it errors on malformed input, or whether it requires the source to be already configured. The phrase 'as the IPT parsed them' hints at parsing behavior but is too vague to be actionable.

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 short sentence with no wasted words. It is front-loaded with the core action ('First rows of a source'). However, it is so terse that it sacrifices clarity for brevity.

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 tool with no output schema, no annotations, and an ambiguous 'source' parameter, the description is incomplete. An agent cannot tell what 'source' refers to, how many rows will be returned, or what the output format looks like. The sibling tools suggest a rich IPT management context, but this description does not provide enough context to invoke the tool correctly.

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

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

Schema description coverage is 50%: the 'shortname' parameter has a description ('Resource shortname'), but 'source' has no description. The tool description does not explain what 'source' means in this context (e.g., a file path, a dataset name, or a source ID). The description adds minimal value beyond the schema, and the undocumented 'source' parameter remains ambiguous.

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 'First rows of a source as the IPT parsed them' conveys a specific verb (peek) and resource (source), and the phrase 'as the IPT parsed them' distinguishes it from a raw file preview. However, it is terse and does not explicitly state what the tool returns or how it relates to sibling tools like ipt_configure_source or validate_tsv.

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 guidance is provided on when to use this tool versus alternatives. The sibling list includes several source-related tools (ipt_configure_source, ipt_add_source, ipt_delete_source), but the description does not mention any of them or specify conditions for choosing this tool.

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

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

No annotations are provided, so the description carries the full burden. It discloses that this is a write operation ('[writes to the IPT]'), that it validates first, refuses on pre-flight problems, waits by default, and notes the public-resource nuance. It does not mention the confirm parameter requirement, but that is covered in the schema. Overall, it adds substantial behavioral context beyond 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?

The description is concise, with every sentence serving a purpose: it states the action, the validation step, the refusal behavior, the default waiting behavior, and a practical caveat about public visibility. It is front-loaded with the key action and reads 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?

Given 5 parameters and no output schema, the description covers the core action and key behaviors but omits details about the return value, the confirm requirement (though in schema), and the semantics of metadataOnly and summary. An agent could call it correctly with shortname and confirm, but might not fully understand all options or outcomes. It is adequate but not exhaustive.

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 60% (3 of 5 parameters have descriptions). The description adds context for the wait parameter ('Waits for completion by default'), which is not described in the schema. However, it does not explain metadataOnly or summary beyond what the schema says, and the metadataOnly parameter lacks any schema description, leaving a gap. The description compensates only partially for the moderate coverage.

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 action (publish), the resource (new version DwC-A + EML), and the validation precondition. It also distinguishes from validation-only tools by saying 'Validate then publish' and 'Refuses when the pre-flight finds problems,' making the purpose unambiguous even without naming 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 when to use it (to publish a resource version) and provides a useful note about making a resource public, but it does not explicitly state when not to use it or mention alternatives like ipt_validate_resource or ipt_get_publication_status. The guidance is implicit rather than explicit.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses that the operation writes/replaces, but it does not warn that existing metadata will be overwritten, nor does it explain the confirm gate or validation 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?

The description is one concise sentence with no redundant filler. The bracketed '[writes to the IPT]' hint adds a useful side-effect signal without bloating the text.

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?

Without annotations or an output schema, a destructive metadata-replacement tool needs more context about overwrite consequences, required confirmation, and validation effects. The description and schema leave these gaps to the agent.

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 50%, so the description needs to help with undocumented parameters. It adds 'local path' meaning to path, but it does not clarify validate or confirm beyond the schema's existing confirm description. Partial compensation only.

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 ('Replace'), the resource ('resource's metadata'), and the input source ('an EML file from a local path'). This distinguishes it from siblings like ipt_get_draft_eml or ipt_set_metadata_fields.

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 operation is understandable, but there is no explicit guidance about when to use this tool versus alternatives such as ipt_set_metadata_fields or ipt_validate_resource. The usage context is implied by the verb and resource 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?

With no annotations provided, the description carries the full burden. It states it 'writes to the IPT' (mutation) and explicitly discloses that omitted fields are preserved, clarifying that this is a partial update rather than a full replace. It does not describe failure modes or validation, but the partial-update disclosure is valuable and goes beyond a bare 'set' statement.

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 immediately states the write operation, then lists the fields, and ends with the critical partial-update behavior. Every word earns its place; there is 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 a setter with 8 parameters and no output schema, the description covers the core fields and the update behavior. It does not explain the metadataLanguage parameter or clarify the coreType naming, but given the schema provides enums and descriptions for many params, the description is sufficiently complete for an agent 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?

Schema coverage is 50%, so the description must add meaning. It lists most parameters (title, description, license, language, updateFrequency, coreType as 'type') and adds allowed license values (cczero, ccby, ccbync) beyond the schema. However, it omits metadataLanguage and uses 'type' instead of the schema's coreType, which could cause minor confusion. Still, it adds useful semantic context.

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 a specific action ('Set') on a specific resource (IPT basic metadata) and enumerates the fields it affects (title, description, license, language, update frequency, type). This distinguishes it from sibling tools like ipt_set_contacts or ipt_set_coverage, which target different metadata aspects.

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 provides clear context by listing the exact fields this tool manages, which implicitly tells an agent when to choose it over other set_* siblings. It also includes the behavioral note that omitted fields are left unchanged, which is useful guidance. However, it does not explicitly mention alternatives or exclusions, so it falls short of a 5.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses the write side effect, the replacement behavior, the fact that omitted lists keep current rows, and per-agent required fields. This is meaningful behavioral context beyond what the schema shows.

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, each earning its place: write intent, replacement behavior, and critical validation requirements. The most important behavioral information is front-loaded and there is no extraneous 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?

The description gives the core behavioral and validation constraints, but for a tool with five parameters, nested object fields, no output schema, and no annotations it should also clarify the four agent-list parameters and the role of shortname. It is adequate for a cautious agent but not fully 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 description adds validation semantics not present in the schema, such as the minimum contact/creator requirement, omitted-list retention, and the need for lastName with organisation or position. However, schema description coverage is only 20% and the description never explains the distinct roles of contacts, creators, associatedParties, and metadataProviders, leaving a significant parameter-meaning 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?

The description opens with '[writes to the IPT]' and states a specific action ('Replace agent lists'), so an agent can tell this mutates IPT agent/contact data. It does not enumerate the four list parameters or contrast with siblings, but it is clearly not a tautology and identifies the operation.

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 about when to use this tool instead of siblings like ipt_set_metadata_fields or ipt_replace_eml. The note that the IPT requires at least one contact and one creator is useful as a precondition, but it does not explain selection criteria 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?

The description discloses a write side effect ('writes to the IPT') and partial-update semantics ('only the ones given'), which is useful because no annotations are provided. It does not cover permissions, reversibility, or what happens to existing values within a replaced coverage type beyond the word 'Replace'.

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 with no wasted words. It front-loads the side effect, action, target, and scoping qualifier without repeating schema 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 mutating, four-parameter tool with no annotations and no output schema, this one-sentence description leaves significant operational context undocumented, such as how to clear a coverage category, required authorization, and expected response behavior. The partial-replacement hint helps, but the definition is still incomplete for safe use.

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 adds a meaningful semantic: only supplied coverage categories are replaced, so omitted categories can remain unchanged. However, schema description coverage is only 25%, and the description does little to explain the meaning of nested parameters such as bounding-box coordinates or taxon structures.

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 concrete action ('Replace') and a specific resource ('geographic, taxonomic and/or temporal coverage'), making the tool's scope immediately clear. It distinguishes this tool from the many sibling metadata, mapping, and EML tools without repeating the tool name.

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

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

The phrase 'Replace geographic, taxonomic and/or temporal coverage' implies this tool is for updating coverage, which provides some context. However, it does not explicitly state when to prefer it over sibling set_* tools or when not to use it.

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

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

With no annotations, the description bears full responsibility for behavioral disclosure. It indicates 'Replace' (a destructive overwrite), which is useful, but doesn't mention what happens to unspecified method fields or keywords (e.g., are they left unchanged or cleared?). No mention of authentication, side effects, or that the operation writes to the IPT beyond the parenthetical '[writes to the IPT]'. The 'Replace' term hints at overwriting but doesn't clarify merge 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?

Single sentence, front-loaded with the action and scope. The bracket prefix '[writes to the IPT]' is concise and sets context immediately. No fluff or repetition. It efficiently conveys the core purpose.

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 tool with nested objects and three parameters, the description is too thin. It doesn't clarify whether both 'keywords' and 'methods' must be provided together, how optional fields behave (e.g., if only 'steps' is provided, are 'studyExtent' etc. cleared?), or what the response indicates about success. No output schema means the description should compensate, but it doesn't cover edge cases or provide enough operational detail.

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

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

Schema coverage is low (33% – only shortname has a description). The description helps by listing the components of the 'methods' object (study extent, sampling, quality control, steps) and by indicating that keywords are 'keyword sets', implying thesaurus grouping. However, it doesn't explain the exact structure of the keywords array (array of objects with keywords and thesaurus) or the relationship between methods and keywords. It adds value but doesn't fully compensate for the schema 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?

Description clearly states the action ('Replace') and the resource ('IPT'), and specifies the scope: keyword sets and/or methods with method sub-fields listed (study extent, sampling, quality control, steps). This distinguishes it from sibling set_* tools that target other metadata aspects. However, it does not explicitly name the input parameter 'shortname' or contrast with similar tools, so slight ambiguity remains.

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 guidance on when to use this tool versus alternatives like ipt_set_metadata_fields or ipt_replace_eml. The description only states what it does, not when it is appropriate or when to prefer another tool. Lack of context on use cases or prerequisites (e.g., must have a resource) makes it hard for an agent to decide.

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?

There are no annotations to carry the safety/mutation burden, so the description is the only behavioral disclosure. It does state '[writes to the IPT]' and that null unmaps a column, which is useful, but it does not reveal whether the mapping is replaced wholesale or merged, what happens to unspecified mappings, or any side effects on existing data.

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

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

A single dense sentence with no filler; the mutation hint and the three key parameter behaviors are front-loaded. The sentence is compact and each clause earns its place, though it is dense enough that a reader may need to parse it twice.

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 write operation with no annotations and no output schema, this description leaves important context missing: the role of mid, valid rowType values, whether the provided mapping replaces the existing one, and what response the agent should expect. It covers the main fields but is not sufficient for confident invocation in complex cases.

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 only documents shortname (17% coverage), so the description must compensate. It adds meaningful semantics for columns, defaults, and idColumn, but leaves mid and rowType unexplained, and does not clarify how columns/defaults interact or which parameters are needed beyond shortname and rowType.

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 uses the specific verb 'Adjust' with the resource 'a mapping' and explains the three main configuration aspects (columns, defaults, idColumn). This clearly implies modification of an existing mapping, which separates it from siblings like add_mapping, delete_mapping, and get_mapping, though it does not name the alternative tools 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 description implies the tool is for modifying an existing IPT mapping, and the parameter explanations hint at when it is useful (changing column mappings, constant defaults, or the ID column). It does not state when to prefer add_mapping or delete_mapping, nor any exclusions or prerequisites such as requiring an existing resource.

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 states that the tool writes to the IPT, implying a mutation, which is consistent with the absence of annotations. It discloses the key behavior of using raw field names and indexed names for repeatable items, which is critical operational context. It doesn't mention potential side effects or permissions required, but given that annotations are absent and the operation is a write, the description carries a reasonable burden.

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 long, directly states the purpose, and front-loads the critical risk warning ('writes to the IPT'). It provides a concrete example of indexed names, which is valuable without being verbose. Every sentence earns its place.

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 nested objects (fields is an object with additionalProperties) and complex semantics. The description explains how to structure repeatable fields and directs to ipt_get_metadata_form for field names. It lacks explicit guidance on which sections are valid or what happens if required fields are missing, but for a generic metadata setter, it covers the essential ambiguity.

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 only 33% (only shortname has a description). The description explains the 'fields' parameter format (raw field names, indexed names), which is not obvious from the schema, and it explains the 'section' parameter implicitly as a container for those fields. It adds significant meaning beyond the schema, which is essential because the schema is sparse.

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 'Save' and the resource 'metadata section by raw field names', distinguishing it from other ipt_set_* tools that save specific sections like contacts or coverage. It explicitly mentions the companion tool ipt_get_metadata_form for retrieving field names, which helps differentiate it from ipt_get_draft_eml and similar tools. However, it doesn't explicitly name a sibling to contrast with, but the purpose is clear enough.

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 that this tool is for saving arbitrary metadata fields not covered by more specific setters (like ipt_set_contacts or ipt_set_coverage), and it tells the user to obtain field names via ipt_get_metadata_form, which is an explicit prerequisite. It doesn't explicitly state when not to use it (e.g., when a dedicated setter exists), but the general context is clear.

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 full behavioral disclosure. It does state '[writes to the IPT]' which indicates a mutation, but gives no details on permission requirements, whether existing settings are overwritten or merged, reversibility, or side effects. This is minimal transparency for a write 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 sentence, which is efficient, but it is a run-on with parentheses and an ellipsis that makes it slightly awkward. It front-loads the write indication, but the structure is not clean or fully readable.

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

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

For a write tool with no output schema, no annotations, and incomplete schema coverage, this description is insufficient. It fails to explain the exact behavior for each page type, what the values object should contain, error handling, or success indication. An agent would struggle to invoke it correctly without external knowledge.

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 only 33% (only shortname has a description). The description partially compensates by listing example keys for the values object (updateFrequency, skipUnchanged, etc.), which adds meaning beyond the generic object schema. However, it doesn't explain the page parameter or the full value set, leaving significant 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?

The description clearly states the tool saves publication options on the IPT, with the verb 'Save' and resource 'publication options'. It even lists sample fields like updateFrequency. It is distinct from the sibling get_settings (read) and other set_* tools that target different aspects, though it doesn't explicitly name an 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?

No guidance on when to use this tool versus alternatives, or when not to. It does not explain the two page enum values (auto-publish vs publication-settings) or any prerequisites. The description merely asserts the action without contextualizing it among the many ipt_set_* siblings.

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 mentions that it 'writes to the IPT' and that the change applies at the next publication, which is useful. However, it omits the critical requirement that the 'confirm' parameter must be true to actually perform the action—a significant behavioral detail that could lead to unexpected no-ops. It also does not mention reversibility 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 front-loads the core action. Every word serves a purpose, and it is easy to scan. There is no padding or redundancy.

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

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

For a mutation tool with three parameters and no output schema, the description is incomplete. It fails to mention the confirmation requirement, which is essential for correct invocation, and offers no usage guidance or alternatives. While it does note the timing of the change, an agent would still need to open the schema to discover the confirm flag, making the description insufficient for safe and correct use.

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 covers all parameters with descriptions: shortname, visibility (enum), and confirm with its own description. Since schema description coverage is 67% and the schema already documents all three parameters, the description adds little extra meaning. The description only hints at the visibility parameter but does not elaborate on the others beyond what the schema provides.

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

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

The description clearly states the action: 'Request public/private visibility' with the resource shortname. It specifies the resource and the visibility change, making the purpose unambiguous. However, it does not differentiate from sibling tools, such as ipt_set_basic_metadata or ipt_set_settings, though the action is distinct enough on its own.

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, and no exclusions or prerequisites. The only contextual note is that the change applies at the next publication, but that is a timing detail, not usage guidance. An agent has no information about when this tool should be preferred 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, the description carries the full behavioral burden. It discloses an important trait: validation results are not enforced by the IPT, so the tool is advisory rather than blocking. 'Pre-flight check' also implies read-only inspection, though the description does not explicitly state side-effect-freedom, auth needs, or output format. The non-blocking disclosure adds genuine value beyond the tool 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?

Two sentences, front-loaded with the core purpose, followed by a critical caveat. No filler words; every clause earns its place, including the specific list of validation checks and the IPT non-blocking note.

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

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

For a simple 2-parameter validation tool, the description covers what the tool checks and its non-blocking nature. It does not describe the return payload or error behavior, and there is no output schema to fill that gap, so an agent must infer what a validation result looks like. Still, the essential context for invoking with a shortname and interpreting the advisory role is present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not elaborate on shortname or metadataOnly; it only references general validation categories. The schema already documents both parameters adequately, so no compensation is needed.

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 'Pre-flight check before publishing', which is a specific verb (validate) and resource (resource) with clear intent. It enumerates concrete check categories (invalid metadata per section, missing/unanalysed sources, missing mappings, unmapped required terms), distinguishing it from siblings like ipt_publish or validate_tsv. The purpose is unmistakable.

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 'Pre-flight check before publishing' explicitly situates this tool in the workflow, telling the agent to run it prior to ipt_publish. It does not name sibling alternatives or exclusion criteria, but the 'before publishing' framing provides enough context for when to invoke it. The caveat 'the IPT itself does NOT block these' also helps the agent understand this is an advisory check, not a gate.

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. It discloses that the tool streams and is safe for multi-GB files, which is important behavioral context. It also lists the specific validation checks. However, it does not explicitly state whether the tool is read-only (though 'validate' implies no mutation) or describe the return format. Still, it provides substantial behavioral insight beyond the 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, well-structured sentence that front-loads the primary purpose ('Validate a local Darwin Core text file BEFORE uploading it') and then lists the specific checks in a compact, scannable format. No wasted words; every element 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?

The description covers the validation scope and streaming behavior, but it does not describe the return value or issue format, which is critical for an agent to interpret results. Since there is no output schema, the description should explain what the agent will receive (e.g., a list of issues). This gap makes the tool incomplete for full autonomous usage.

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 25% (only 'path' has a description). The description mentions 'duplicate occurrenceID', which hints at the idColumn parameter, but it does not explain the meaning of 'delimiter' or 'maxIssues'. With such low coverage, the description should compensate by explaining all parameters, but it only partially addresses them, leaving two parameters 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 clearly states the tool's purpose: validating a local Darwin Core text file before upload. It lists specific checks (column-count consistency, UTF-8/mojibake, date/lat-long ranges, duplicate occurrenceID), which is more specific than a generic 'validate' and distinguishes it from sibling ipt_validate_resource (which validates an uploaded resource on the IPT side).

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 'BEFORE uploading it' provides clear temporal context and implies this tool is for local pre-upload validation. It doesn't explicitly mention alternatives or when not to use it, but the context is sufficient to route an agent away from server-side validation tools. Missing explicit exclusions, but the guidance is clear.

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