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

With no annotations, the description carries the full burden of behavioral disclosure, but it only states the create action. It does not mention required permissions, idempotency, duplicate handling, rate limits, 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, front-loaded sentence with no filler. It is structurally concise, though extremely brief.

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, no output schema, and no annotations, a single sentence is insufficient. It does not explain the account object, required fields beyond the schema, or what the response contains, leaving the agent without enough context for confident 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?

All 7 parameters are fully described in the input schema, so the description does not need to repeat parameter details. However, it adds no extra semantic meaning beyond what the schema already provides, so the 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 uses the specific verb 'Create' with the resource 'account,' clearly differentiating it from sibling tools like pylon_update_account, pylon_list_accounts, and pylon_get_account. It is unambiguous and action-oriented.

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, no prerequisites, and no exclusions. The description simply states the action without any contextual usage information.

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. However, it only repeats the operation name and does not disclose any side effects, permission requirements, default behaviors (e.g., is_published default false), or response format. This is essentially a tautology of 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?

The description is a single sentence, but it is under-specified rather than concise. It restates the tool name without adding informative content. Every word should add value, but here it doesn't.

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

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

Given the tool's complexity (10 parameters, nested objects, 4 required fields) and lack of output schema or annotations, a one-sentence description is completely inadequate. There is no mention of return behavior, prerequisites, or how nested objects like visibility_config interact with other parameters.

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?

All 10 parameters have descriptions in the schema, meeting the 100% coverage threshold, so the baseline is 3. The description itself adds no additional meaning to the parameters; it doesn't mention defaults, relationships, or important considerations beyond the schema.

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

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

The description clearly states the specific action (create) and resource (article within a knowledge base). It distinguishes from sibling tools like update_article, delete_article, and list_articles by specifying 'new article'. This is a specific verb+resource with clear 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?

The description offers no guidance on when to use this tool vs alternatives, such as prerequisites (e.g., existence of a knowledge base) or scenarios where update_article would be more appropriate. The only implied usage is that it creates a new article, but this is evident from the 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 only states the operation without detailing side effects, return values, or constraints such as nesting via parent_collection_id, which is not addressed.

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

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

The description is a single concise sentence that is front-loaded with the verb and resource. Every word is necessary, 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 tool with no output schema, the description does not explain the return value or outcomes. It also fails to mention nested collections (parent_collection_id) despite the schema supporting it, making it under-specified for a CRUD 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 100%, so the schema already documents all five parameters. The description adds no additional parameter semantics, meeting the baseline for 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 clearly states the tool's action ('Create'), resource ('collection'), and scope ('within a knowledge base'), distinguishing it from sibling tools like list_collections and get_collection. It is specific and unambiguous.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention any prerequisites, exclusions, or relationship to other collection-related tools, leaving usage entirely implied.

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

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

Annotations are absent, so the description carries full responsibility for behavioral disclosure. It only conveys the action (create) without revealing side effects, duplicate handling, permission requirements, or return behavior. This is insufficient for a mutation tool with no annotation support.

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

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

The description is a single, front-loaded sentence with no fluff or repetition. It is appropriately concise for the action described, earning a perfect score for efficiency.

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

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

Given the tool's complexity (8 parameters, enums, nested objects, no output schema), the one-sentence description is inadequate. It does not mention key contextual details such as the relationship between object_type and type, the conditional need for select_options, or what happens after creation. The schema provides structure but not usage context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific guidance, leaving the schema to fully document parameters. It does not compensate for any tricky interactions like select_options being relevant only for select/multiselect types.

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 exactly what the tool does: 'Create a new custom field in Pylon.' It uses a specific verb (create) and resource (custom field), clearly distinguishing it from sibling tools like pylon_update_custom_field, pylon_list_custom_fields, and pylon_get_custom_field.

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. There are no mentions of prerequisites, exclusions, or typical use cases. Sibling tools are not referenced, leaving the agent 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It merely restates the action 'create' without explaining side effects, permissions, required fields, or what the response will be. This is essentially a tautology and provides no transparency 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?

The description is a single, efficient sentence with no filler or redundancy. It is concise and front-loaded, though it is under-specified rather than appropriately sized.

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

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

With no annotations, no output schema, and a bare description, the tool lacks contextual completeness. The schema documents parameters, but the description does not explain when to use the tool, what the created issue entails, or what to expect in return. It is too minimal for a create operation with 8 parameters.

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%, with all 8 parameters having descriptions. The description adds no additional meaning beyond the schema, 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 action ('Create') and the resource ('a new issue in Pylon'). It is a specific verb+resource combination that distinguishes it from sibling tools like update_issue or list_issues, though it doesn't elaborate on what constitutes an issue.

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 over alternatives. There is no mention of prerequisites, contexts, or exclusions, and sibling tools like pylon_update_issue or pylon_search_issues are not referenced.

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

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

No annotations are provided, so the description carries the full burden. It only mentions the rate limit, but does not disclose side effects, permissions, return values, or any operational behavior beyond the creation itself. For a mutation tool, this is insufficient.

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 and front-loaded with the purpose. The second sentence provides a rate limit constraint, which is useful but not essential. It is efficient without being under-specified.

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

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

The tool has no output schema or annotations, and the description does not explain what happens after creation, any prerequisites, or return value. While the schema documents parameters, the overall context is incomplete for an agent to fully anticipate the tool's behavior.

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 already provides full descriptions for all four parameters (100% coverage). The description adds no additional parameter semantics, but the schema compensates, so the baseline of 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 clearly states the action ('Create') and the resource ('a new milestone in Pylon'), which unambiguously distinguishes it from sibling tools like update_milestone and delete_milestone. It is a specific, action-oriented statement.

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 explicit when-to-use or alternative guidance. The purpose implies usage, but no prerequisites or exclusions are mentioned, so it relies on the tool's name for 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?

With no annotations, the description carries the full burden of disclosing behavior. It only mentions the rate limit but does not describe side effects, required parameters, return values, or error conditions, which are critical for a mutation 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 two short sentences, front-loaded with the core purpose and followed by a useful rate-limit note. No superfluous text, 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?

For an 8-parameter mutation tool with no output schema and no annotations, the description is incomplete. It lacks information about return values, prerequisites (e.g., valid account_id), and behavioral expectations, making it insufficient for full context.

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

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

The input schema has 100% description coverage for all 8 parameters, so the schema already provides semantics. The description adds no parameter-specific information, making a baseline score of 3 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 clearly states the action ('Create') and the resource ('a new project in Pylon'), which is specific and distinguishes it from sibling tools that update or delete projects. The verb+resource structure is unambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention any context, exclusions, or sibling tools for comparison, leaving the agent to infer usage solely 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?

The description only states the action without disclosing side effects, permissions, idempotency, or return values. Since no annotations are provided, the description carries the full burden but offers minimal behavioral context.

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

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

One sentence, front-loaded with the core action, no extraneous words.

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

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

The tool has 5 parameters and no output schema. The description provides a clear purpose but omits behavioral details, and the schema covers parameter definitions, leaving the overall context adequate but minimal.

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?

All 5 parameters have schema descriptions (100% coverage), so the baseline is 3. The phrases 'mapping a source path to an article or collection' add slight semantic context but do not meaningfully expand on 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 uses the specific verb 'Create' with the resource 'path redirect' and clarifies it maps a source path to an article or collection, clearly distinguishing it from article/collection creation 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?

No explicit when-to-use or alternative tool is mentioned. The context 'within a knowledge base' implies it's for KB redirects, but it does not exclude other operations like creating articles directly.

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 of behavioral disclosure. It mentions a rate limit of 60 requests per minute, which is useful, but it does not disclose response format, error conditions, or authentication requirements, leaving gaps for a mutation 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 two sentences and to the point. The rate limit information earns its place as it provides operational guidance, and there is no unnecessary fluff.

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

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

With 9 parameters and no output schema, the description is too thin. It lacks information on what the response looks like, whether creation is idempotent, or any required permissions, making it incomplete for an agent to fully understand the tool's behavior.

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 fully documents all 9 parameters. The description adds no additional parameter context, but baseline 3 is appropriate since parameters are already well-specified.

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 'Create a new task in Pylon' with a specific verb and resource, clearly indicating the action. It differentiates from sibling tools like pylon_update_task and pylon_delete_task by the resource and action, though it does not explicitly name alternatives.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as pylon_update_task for existing tasks or pylon_create_project for other resources. No prerequisites or context for selection are given.

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

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

The description does not contradict any annotations (none were provided). It adds 'Permanently' which discloses irreversibility, but it lacks details about prerequisites, permissions, or potential cascade effects. With no annotations to fall back on, the description carries the full burden for behavioral disclosure, and while it covers the most critical aspect (permanence), it omits other useful context.

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

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

The description is one short sentence that conveys the essential action and scope. It is front-loaded with the verb and resource, and every word adds value. There is no fluff or redundant 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?

Given the tool's low complexity (two simple string parameters, no output schema) and the schema covering parameters fully, the description is largely complete. It asserts permanence, which is the most critical behavioral context for a delete operation. However, it does not note what happens to linked collections or whether the action is idempotent, which would be useful for a destructive tool, so it's not a perfect 5.

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%, with both parameters (article_id and knowledge_base_id) having clear descriptions. The tool description adds no extra semantic meaning beyond the schema, as it merely mentions 'article' and 'knowledge base' without detailing format or relationships. A baseline of 3 is appropriate since the schema already fully documents each parameter.

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

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

The description uses a specific verb ('delete') with a clear resource ('article') and scope ('from a knowledge base'), making it unambiguous. It also adds 'Permanently', which distinguishes this from a soft delete or archive action. It stands apart from sibling tools like pylon_update_article or pylon_delete_project.

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 implies the tool is for permanently removing an article from a knowledge base, which is the key usage context. It does not explicitly mention alternatives or when-non usage, but the intent is straightforward given the tool's name and sibling context. A brief note that updating is a different operation would have been explicit, but the clarity is sufficient.

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 states the destructive action and a rate limit, but omits important details such as irreversibility, behavior for non-existent milestones, or permission requirements. For a delete operation, this is a significant gap.

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

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

The description is extremely concise: one sentence stating the action plus a rate limit note. There is zero wasted content, and the essential information is front-loaded.

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

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

For a simple one-parameter tool, the description covers the core action and rate limit, and the schema fully documents the parameter. However, the lack of non-obvious behavioral details (e.g., idempotency, error on invalid ID) prevents it from being 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 input schema already provides a 100% description for the only parameter (milestone_id), so the schema carries the semantic weight. The description adds no additional parameter context beyond what the schema states, warranting the baseline score of 3.

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

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

The description uses a specific verb ('Delete') and resource ('existing milestone'), clearly differentiating it from sibling tools like create_milestone and update_milestone. This makes the tool's purpose immediately clear and unambiguous.

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

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

The usage context is implied by the tool's name and description: you use this to delete a milestone. However, there is no explicit guidance on when to choose this over alternatives, nor any mention of prerequisites or exclusions.

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

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

The description adds the rate limit (20 requests per minute), which is useful behavioral context beyond the base action. However, it does not disclose irreversible effects, permission requirements, or cascading deletion behavior, which would be expected for a destructive tool with no annotations.

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 short sentences with the action front-loaded. The rate-limit sentence adds useful context without redundancy or unnecessary detail. Every word 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 simple one-parameter delete tool, the description is minimally adequate. It covers the core purpose and one behavioral constraint (rate limit), but lacks explicit usage guidance and does not explain return values or impossibility of undoing the operation.

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 already provides 100% coverage for the single parameter project_id with a clear description. The tool description adds no additional meaning or clarification beyond what the schema already states.

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

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

The description clearly states the action ('Delete') and the target resource ('an existing project in Pylon'), which is specific and distinct from sibling tools like create/update project. It unambiguously identifies the tool's purpose.

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, no mention of exclusions, prerequisites, or when not to use it. It simply states the action without contextual usage directions.

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

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

With no annotations, the description carries the full burden. It mentions a rate limit (20 requests per minute), which is useful, but it does not disclose that deletion is permanent, possible cascading effects on related data, required permissions, or response behavior. This is a significant gap for a destructive 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 one concise sentence plus an optional rate-limit note. Every word earns its place, with no fluff or repetition of schema details.

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

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

The tool is a simple delete operation, but the description fails to mention irreversibility, side effects, or any prerequisite conditions. Given the destructive nature and lack of annotations or output schema, the description is incomplete for safe and effective 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?

The input schema already provides 100% coverage for task_id with a clear description ('The unique identifier of the task to delete'). The tool description adds no additional parameter context, so a baseline score of 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 uses a specific verb ('Delete') and resource ('existing task in Pylon'), clearly distinguishing it from sibling delete tools for projects, milestones, articles, etc. The one-sentence explanation is unambiguous and action-oriented.

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, prerequisites, or exclusions. The description only states the action and rate limit; it does not mention that this is for tasks specifically or when to prefer it over other delete operations.

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 carry the full burden. It states the action is a read ('Get') and specifies the retrieval key, but it does not disclose potential errors (e.g., not found), authorization requirements, or return format. For a simple get-by-ID tool this is acceptable but minimal.

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 compact sentence that fully communicates the core function without any fluff or redundancy. Every word 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?

Given the tool's simplicity (one parameter, no output schema, no annotations), the description adequately covers the essential usage. It does not describe the return value, but for a 'get by ID' operation the result is reasonably implied as the requested account object. Slightly more detail about error cases would be beneficial.

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% — the single parameter 'account_id' already has a clear description ('The unique identifier of the account'). The description adds no extra semantics beyond what the schema provides, so the baseline score of 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 uses the specific verb 'Get' with a singular resource 'account' and explicitly identifies the lookup mechanism ('by its ID'). This clearly distinguishes it from sibling tools like pylon_list_accounts (listing multiple accounts) and pylon_create_account/pylon_update_account.

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 implied usage is 'when you have an account ID and need the corresponding account,' but the description provides no explicit guidance on when to prefer this tool over alternatives, nor any exclusions. The context is clear but not explicitly 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?

No annotations are provided, so the description carries the burden of disclosing behavior. The description indicates a read operation ('Get') and scopes it to a knowledge base, which implies no side effects. However, it does not explicitly state whether authentication is needed, what happens if the article is not found, or the return format. For a simple get, the description is minimally adequate but lacks richer behavioral context.

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

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

The description is a single, direct sentence with no unnecessary words. It is front-loaded with the verb and resource, making it easy to parse quickly.

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

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

The tool is simple with only two parameters, both documented in the schema. The description confirms the purpose and scoping but does not mention what is returned or any edge cases (e.g., missing article/404). With no output schema, a brief note on return value would improve completeness, but the current state is sufficient for an agent to understand the core operation.

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 descriptions cover 100% of the parameters (article_id and knowledge_base_id) with clear definitions. The description adds no additional parameter meaning beyond what the schema already provides, so it meets the baseline for 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 clearly states the action ('Get'), the resource ('specific article'), and the scope ('by its ID within a knowledge base'). It distinguishes this tool from siblings like pylon_list_articles (which lists multiple articles) and pylon_get_knowledge_base (which gets a knowledge base).

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 a single article by ID within a knowledge base. However, it does not explicitly mention alternatives or exclusions, such as 'use pylon_list_articles to search or browse articles'. The context is clear from the wording but no direct guidance is given.

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

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

With no annotations provided, the description carries the full burden. It states the core read-only behavior ('Get'), which implies non-mutating, but it does not disclose return format, error behavior, or authentication requirements. For a simple GET, this is minimally adequate but lacks rich behavioral context.

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

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

The description is a single, concise sentence with no wasted words. Every word contributes to the meaning, and it is front-loaded with the primary action.

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 retrieval tool with only two parameters and no output schema, the description is largely complete. It clearly states what the tool does and the required context. It lacks return value details, but for a get operation this is often self-evident and not critical for tool selection or 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 100%, and the tool description adds no new meaning beyond paraphrasing the parameters. The description mentions 'by its ID' and 'within a knowledge base', which aligns with collection_id and knowledge_base_id, but does not enrich the parameter semantics beyond what the schema already 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 (Get), the resource (a specific collection), and the scope (by ID within a knowledge base). It unambiguously differentiates from sibling tools like list_collections, which retrieves all collections, and create_collection.

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

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

The description implies usage when you have a collection ID and knowledge base ID, but it does not explicitly state when to use it over alternatives like list_collections, nor does it mention any exclusions. The context is clear but no explicit guidance on alternative tools.

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 must carry the full behavioral burden. It only states 'Get a specific custom field by its ID,' which essentially restates the action already implied by the tool's name. No additional behavioral traits (e.g., error handling, authentication, side-effect safety, rate limits) are disclosed, leaving significant transparency gaps.

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

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

The description is a single, front-loaded sentence with no filler or redundant information. It concisely captures the core purpose and uses no unnecessary words, achieving maximum efficiency.

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 only one parameter and no output schema or annotations, the description provides the essential purpose but omits expected return value structure and error behavior. It is minimally adequate for a simple getter but leaves the caller to infer what a successful response looks like and what happens if the ID is not found.

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 already describes custom_field_id as 'The unique identifier of the custom field' with 100% coverage. The description's phrase 'by its ID' adds minimal semantic value beyond the schema, so it meets the baseline for adequate schema coverage without further enrichment.

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') and resource ('a specific custom field'), and specifies that it is retrieved 'by its ID', which distinguishes it from sibling tools like pylon_list_custom_fields (which lists all) and pylon_update_custom_field (which mutates). This clearly identifies the tool's function and 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?

The description implies usage when a specific custom_field_id is known, but does not explicitly mention alternatives like pylon_list_custom_fields for retrieving multiple fields, nor does it provide when-not-to-use guidance. Usage context is clear from the wording but lacks explicit alternatives or exclusions.

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

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

No annotations are provided, and the description only states 'Get', implying a read operation without disclosing error behaviors, permissions, rate limits, or response details. The description does not add meaningful behavioral context beyond the verb itself.

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

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

The description is a single, concise sentence with no filler or redundancy. The primary action ('Get a specific issue') is front-loaded, and every word contributes to the meaning.

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 get-by-ID tool, the description covers the core purpose, but it lacks context about return value structure, error handling (e.g., not found), and any behavioral nuances. With no output schema or annotations, the description should provide a bit more detail to be 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 input schema already provides a full description for issue_id (100% coverage). The description adds no new parameter semantics beyond restating the parameter's purpose, so it meets the baseline for 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 uses a specific verb 'Get' with the resource 'issue' and scopes it to 'by its ID', clearly distinguishing it from list/search tools that retrieve multiple issues. It unambiguously indicates the action and target.

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

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

The phrase 'by its ID' implies this tool is for when a specific issue identifier is known, but there is no explicit guidance on when to prefer this over pylon_list_issues or pylon_search_issues, and no alternatives are mentioned.

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 must fully disclose behavior. It says 'all messages' but the schema's limit parameter with a default of 100 suggests pagination, making 'all' potentially misleading. No mention of return format, ordering, auth, or pagination behavior. The lack of transparency around the 'all' claim is a significant gap.

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

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

The description is a single concise sentence with no wasted words. It is front-loaded with the verb and resource, and every word contributes to understanding the tool's 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?

Given the lack of output schema and annotations, the description should provide more context. It does not explain return structure, pagination, or the fact that 'all' may require multiple calls. For a tool with 3 parameters and a potential gap between 'all' and the default limit, this is insufficient.

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 provides complete parameter meanings. The description adds no additional parameter semantics. Baseline 3 is appropriate because the schema carries the full explanatory burden and does so adequately.

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 'Get all messages for a specific issue' uses a specific verb ('Get') and resource ('messages for a specific issue'), clearly distinguishing it from sibling tools like pylon_get_issue (issue details) and pylon_list_issues (list issues). The purpose is unambiguous.

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

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

The description implies usage context—use when you need messages for a particular issue—but provides no explicit guidance on when not to use it or alternatives. Sibling tools have similar names, yet no differentiation is mentioned. The context is clear but not elaborated.

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 'Get a specific knowledge base by its ID' without revealing potential behaviors such as error handling (e.g., 404 if not found), return format, permissions, or read-only guarantee. The verb 'Get' implies a read operation, but no additional context is offered.

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, complete sentence that front-loads the action and the key qualifier. There is zero extraneous content; every word contributes to clarity.

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 extreme simplicity of the tool (one required parameter, no output schema), the description is sufficient for an agent to know what the tool does and what input to provide. It lacks return format or error behavior, but for a simple get-by-ID tool, the context is adequately complete.

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

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

Schema coverage is 100% for the single parameter, knowledge_base_id, which is well described in the schema. The description repeats 'by its ID' but does not add extra semantic meaning beyond what the schema already provides. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the verb 'Get', the resource 'knowledge base', and the specific scope 'by its ID'. This distinguishes it from sibling tools like pylon_list_knowledge_bases, which lists all bases, and pylon_get_article, which targets a different resource. The purpose is unambiguous and directly tied to the tool's 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 description implies usage when you have a specific knowledge base ID, but it does not explicitly mention when to prefer this tool over alternatives (e.g., using list_knowledge_bases if you don't have the ID). There is no exclusion or alternative guidance, but the simple scope makes the intended usage reasonably 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?

No annotations are provided, so the description alone must convey behavioral traits. It discloses both linking and unlinking actions, but omits any side effects (e.g., whether unlinking affects the external issue), permissions required, or error behavior. The "remove" operation is a destructive act yet is not flagged as such.

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 action (link or unlink) and includes the key sources. There is no fluff, repetition, or irrelevant detail.

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?

Combined with a fully described schema, the description covers the essential purpose and supported operations, making the tool's behavior clear. While it omits return values and edge cases, the simplicity of the operation and absence of an output schema make this an acceptable level of completeness.

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 already provides full descriptions for all four parameters, including enums for 'source' and 'operation', achieving 100% coverage. The description adds no additional parameter-level meaning beyond what the schema already documents, 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 uses the specific verb "link or unlink" and names the resource "external issues ... to/from a Pylon issue", clearly distinguishing it from sibling tools, none of which handle external issue linkage. It also enumerates the supported source systems (Linear, Asana, Jira, GitHub) to further clarify 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?

The description provides clear context for when to use the tool—to manage links between Pylon issues and external systems—by naming the supported external platforms. It does not explicitly state when not to use it or mention alternatives, but no sibling tool overlaps with this functionality, so exclusions are unnecessary.

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 states 'List all accounts' and 'optional pagination,' but does not disclose ordering, whether archived/deleted accounts are included, rate limits, or the response structure. Adequate for a simple read operation but lacks depth.

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 conveys the core purpose and a key optional behavior. Every word 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 simple list endpoint with well-documented parameters and no output schema, the description sufficiently covers the resource and pagination. It could mention the default limit or return shape, but those are not strictly required for this level of complexity.

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

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

Schema description coverage is 100%, with limit and cursor clearly documented in the input schema. The description adds 'optional pagination,' which aligns with the parameters but does not add new meaning beyond the schema.

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

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

The description clearly states the verb 'List' and resource 'accounts' in Pylon, with the optional pagination qualifier. It is easily distinguished from sibling tools like pylon_get_account (single account) and pylon_create_account.

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 retrieving multiple accounts, but it does not explicitly state when to use it instead of alternatives, such as get_account for a single account, or mention any exclusion 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?

With no annotations provided, the description carries full responsibility for disclosing behavioral traits. It only mentions 'optional pagination' and does not reveal details such as ordering, filtering, authorization requirements, or whether archived or draft articles are included. This is a significant gap for a 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 a single, concise sentence that front-loads the core purpose. It contains no wasted words and is easy to parse quickly.

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

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

Given the tool's simplicity (3 parameters, no output schema), the description is adequate but lacks some completeness. It does not specify what the returned article objects look like or mention any default ordering or limits beyond the schema. However, for a simple list operation, this is a minor gap.

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

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

The input schema has 100% coverage with descriptions for all three parameters, so the baseline is 3. The description adds no extra meaning beyond what the schema already provides, merely noting 'optional pagination' which is already implied by the limit and cursor parameters.

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 ('List'), the resource ('articles'), and the scope ('in a knowledge base'), which distinguishes it from sibling tools like get_article, create_article, or update_article. The addition of 'optional pagination' further clarifies the behavior.

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 for when to use the tool (listing articles within a specific knowledge base). It does not explicitly mention alternatives or exclusions, but the purpose alone differentiates it from related tools like pylon_get_article for single articles.

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 carry full burden. It only states the basic action and scope, without disclosing any behavioral nuances such as pagination, access restrictions, error handling, or return format. This is comparable to the update_drive example that scored 2 for lacking permission/side-effect details.

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

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

The description is a single concise sentence with no filler. It front-loads the verb and resource, making it immediately clear and easy to scan.

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

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

With only one parameter and no output schema, the description is minimal but adequate for a simple list operation. However, it lacks details about return format, pagination, or behaviors on invalid IDs, leaving some gaps for an agent to resolve.

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

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

Schema description coverage is 100% for knowledge_base_id, so the schema already documents the parameter. The description adds no extra parameter semantics beyond what the schema provides, meriting the baseline score of 3.

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

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

The description uses a specific verb 'List' plus resource 'collections' and scope 'in a knowledge base', clearly distinguishing it from sibling tools like pylon_get_collection (single collection) and pylon_list_knowledge_bases (different resource).

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

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

The description clearly indicates when to use this tool (to list collections for a given knowledge base) and the required knowledge_base_id parameter is obvious. However, it does not explicitly mention exclusions or alternatives, such as using pylon_get_collection for a single collection.

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 does not explicitly state the operation is read-only, nor does it disclose pagination behavior despite the cursor parameter. No mention of permissions, rate limits, or return format.

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, front-loaded with the action and resource, and contains no redundant words. It is effectively concise given the tool's simplicity.

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 basic purpose but omits pagination behavior (despite a cursor parameter) and any return format details. With no output schema, this is a gap, but the tool has only 2 parameters and is relatively simple, so the description is minimally adequate with room for improvement.

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

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

The input schema has 100% description coverage for both parameters (cursor as 'Pagination cursor' and object_type with enum values). The description repeats 'specific object type' but adds no additional parameter-level meaning beyond the schema, so 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 clearly states the action (List), the resource (custom fields), and the scope (for a specific object type). It distinguishes from sibling tools like pylon_get_custom_field (single field) and pylon_create_custom_field/update_custom_field.

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 retrieving all custom fields for a given object type, but provides no explicit guidance on when to use this tool versus alternatives like pylon_get_custom_field or pylon_list_accounts. No exclusions or alternative conditions are mentioned.

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 only states 'List issues within a time range,' which implies a read-only operation but does not disclose pagination behavior, default limit, ordering, or what the returned list contains. The presence of cursor and limit parameters in the schema highlights missing behavioral context.

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

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

The description is a single, concise sentence that front-loads the action ('List issues') and includes the key qualifier ('within a time range'). There is no redundant or extraneous 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?

The tool is a relatively simple list operation with well-documented parameters in the schema. However, with no output schema and no annotations, the description omits behavioral details such as pagination, result format, and whether the listing is ordered. The core purpose is clear, but additional context would improve completeness.

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 adds minimal meaning by indicating the time range is the core filter, but it does not elaborate on limit/cursor semantics beyond what the schema already provides. The parameter descriptions in the schema are sufficient, so this score 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 clearly states the tool's purpose: 'List issues within a time range in Pylon.' It uses a specific verb ('List') and resource ('issues'), and the time-range qualifier distinguishes it from related tools like pylon_get_issue (singular) and pylon_search_issues (search-based).

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 such as pylon_search_issues or pylon_get_issue. It does not mention exclusions or recommend an alternative for different use cases. The only hint is the time range, but this 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. It states the action is to list all knowledge bases at the organization level, which implies a read-only, comprehensive operation. However, it does not disclose any potential side effects, pagination, or return format details. For a simple list tool, this is adequate.

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

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

The description is a single, front-loaded sentence with no redundant words. It is appropriately concise and every word 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?

Given the simplicity of the tool (0 parameters, no output schema), the description adequately covers the core function. It does not mention potential nuances like pagination or filtering, but with no parameters, listing all knowledge bases in the organization is likely the full behavior. A note about returning a list would be helpful but is not critical.

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 input schema is empty. The description does not need to add parameter information, and the baseline of 4 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 uses the specific verb 'List' with the resource 'knowledge bases' and scope 'organization', clearly distinguishing it from sibling tools like pylon_get_knowledge_base (single item) and pylon_list_articles (different resource). It directly states what the tool does.

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

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

The description implies the tool is for listing all knowledge bases, but it does not explicitly state when to use this over alternatives like pylon_get_knowledge_base or pylon_list_articles. No exclusions or alternatives are mentioned.

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 present, so the description carries the full burden of behavioral disclosure. It only states the action without mentioning whether redaction is irreversible, affects related data, or requires special permissions. This is insufficient for a mutation 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, front-loaded sentence with no filler or redundant information. It is appropriately sized given the simplicity of the tool, though it could be more expansive on behavior without losing conciseness.

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

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

With no output schema and no annotations, the description should explain what redaction does, its permanence, and any side effects. It only states the action, leaving the agent without critical context for a mutation tool. This is incomplete.

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 covers both parameters (issue_id and message_id) with clear descriptions, achieving 100% coverage. The tool description adds no parameter-specific meaning beyond what the schema already provides, so the baseline of 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 'Redact a specific message in an issue' uses a specific verb ('redact') and identifies the resource ('message in an issue'). It clearly distinguishes from sibling tools like get_issue_messages or update_issue, as none of them explicitly mention redaction.

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

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

The description implies usage when a message needs to be redacted, but provides no explicit when-to-use or alternative guidance. Given the number of sibling tools, more context would be helpful, but the purpose itself offers a clear implied use case.

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 query capabilities (AND/OR, nested filters) and common fields, but does not state whether this is strictly read-only, mention pagination behavior, or describe response format. For a search tool, these are notable omissions, though the name implies read-only behavior.

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

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

Two sentences with no fluff. The first sentence states the core purpose, and the second expands on query capabilities and filter fields. Information density is high and 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 search tool with a nested filter object and no output schema, the description covers purpose, filter capabilities, and common fields. It doesn't explain pagination details, but those are in the parameter schema. Overall, it provides sufficient context for an agent to select and 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 coverage is 100%, so the baseline is 3. The description adds valuable context beyond the schema by listing common filter fields (state, priority, assignee_id, etc.) and reiterating the nested filter and operator capabilities, which helps agents construct valid filters without external knowledge.

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 ('Search') and resource ('issues in Pylon'), and immediately distinguishes this tool from siblings like list_issues by emphasizing filter-based searching and complex query support. It also lists common filter fields, making the scope explicit.

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

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

The description implies usage context by highlighting complex queries with AND/OR and nested filters, suggesting this is the tool for advanced filtering. It does not explicitly mention when not to use it or contrast with list_issues/get_issue, but the context is clear enough without exclusions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not state whether the update is partial or full, what the tool returns, whether changes are reversible, or any side effects. This is a significant gap for a mutation 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, concise sentence with no unnecessary words, making it easy to parse. While it lacks structured elements like exclusions or related domain info, it is appropriately minimal for a simple update operation.

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 8 parameters, no annotations, and no output schema, the description is severely under-specified. It fails to convey expected outputs, update semantics, error behavior, or any context that would help an agent efficiently invoke the tool.

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

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

The input schema provides descriptive comments for all 8 parameters, including nested custom_fields, achieving 100% schema coverage. The description adds no additional parameter context, but the schema is sufficient to understand each parameter's purpose.

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 ('update') and the resource ('existing account in Pylon'), which distinguishes it from sibling tools like pylon_create_account, pylon_get_account, and pylon_list_accounts. However, it could be more specific about what fields or aspects of the account are updatable.

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 when to prefer pylon_update_account over pylon_update_custom_field, nor does it indicate prerequisites such as having an existing account ID.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It does disclose a key partial-update behavior: 'Only provided fields are modified.' However, it does not mention permissions, side effects, default publish behavior, or what happens with nested visibility_config, leaving significant behavioral gaps.

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, clear sentence that opens with the core purpose and immediately adds the key behavioral constraint. No wasted words; it is perfectly concise and 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?

The tool has 7 parameters, a nested object, and no output schema. The description is minimal, relying heavily on the schema for parameter details. It lacks context on return values, error conditions, prerequisites (like required IDs), or behavior of the publish flag. While the schema fills gaps, the description itself does not provide enough contextual completeness for a tool of this complexity.

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

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

Schema coverage is 100%, so each parameter already has a description. The tool description adds value by clarifying the semantics across parameters: only provided fields are modified, meaning omitted parameters retain their existing values. This overrides individual parameter descriptions and is a meaningful addition.

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 action ('Update an existing article') and its scope ('in a knowledge base'). It distinguishes itself from sibling tools like create_article, get_article, and delete_article by specifying the update verb and the partial-update behavior.

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: this tool is for updating existing articles, not creating new ones. It also notes that only explicitly provided fields are modified, which is a useful usage directive. However, it does not explicitly mention alternatives or when-not-to-use scenarios, though the sibling tool names make this fairly obvious.

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 only states 'update an existing custom field' but does not explain whether it performs a partial update, whether all fields are required, authorization needs, side effects, or what is returned. For a mutation tool, this is a significant gap.

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

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

The description is a single sentence with no redundancy. It is front-loaded and free of filler, entirely appropriate for a simple CRUD operation.

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

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

With 7 parameters and no output schema or annotations, the description should provide more context about update behavior and return values. It does not clarify how to use fields like default_value vs default_values, or whether select_options must be provided in full. The description is not complete for successful invocation beyond the basic purpose.

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 covers 100% of parameters with descriptions, so the baseline is 3. The description adds no further semantic detail beyond the schema, which provides minimal descriptions like 'Slug identifier' and 'Label'.

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 'Update an existing custom field in Pylon' clearly identifies the action (update), the resource (custom field), and the scope (existing). This distinguishes it from sibling tools like pylon_create_custom_field, pylon_get_custom_field, and pylon_list_custom_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 description provides no guidance on when to use this tool versus alternatives such as pylon_create_custom_field or pylon_get_custom_field. It does not mention prerequisites, exclusions, or decision criteria for selecting 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?

With no annotations, the description must disclose behavioral traits but only says 'update'. It does not mention whether this is a partial or full update, error behavior for nonexistent issues, or permission requirements. The mutation aspect is implied by the verb, but no additional transparency is offered.

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

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

The description is a single concise sentence with no superfluous words. It is front-loaded and efficiently communicates 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?

With 7 parameters, no output schema, and no annotations, the description is severely under-specified. It lacks any information about update semantics, optionality, return values, or errors, making it insufficient for an AI agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds no parameter-specific meaning beyond what the schema already documents. It does not compensate for the lack of usage context, but does not need to since the schema covers all parameters.

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 'update' and the resource 'existing issue', which distinguishes it from create, get, and list operations on issues. It does not mention specific fields, but the action is unambiguous.

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

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

No guidance is provided on when to use this tool versus alternatives like pylon_create_issue or pylon_update_task. The description gives no context for selection or prerequisites.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals a rate limit of 60 requests per minute, but does not describe effects, partial update semantics, error conditions, or any required permissions. This is a mutation tool, so more transparency is expected.

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

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

The description is concise and front-loaded: two short sentences, with the core purpose stated first and the rate limit appended. Every word serves a purpose, and there is no redundant 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 simple update tool with three well-documented parameters, the description and schema together provide sufficient context. The rate limit adds useful behavioral information, and no output schema is present, so return-value documentation is not required. It lacks usage guidance, but that is captured separately.

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 already covers all three parameters with descriptive text (100% coverage), so the baseline is 3. The description adds no additional meaning about parameters beyond what the schema provides, such as how fields are applied or whether partial updates are supported.

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 ('Update') and resource ('an existing milestone in Pylon'), distinguishing it from sibling tools like pylon_create_milestone and pylon_delete_milestone. It is specific and unambiguous.

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

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

No guidance is provided about when to use this tool versus alternatives. The word 'existing' implies the milestone must already exist, but there is no explicit mention of when to choose update over create/delete, nor any mention of required prerequisites.

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

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

With no annotations, the description must disclose behavior but only mentions a rate limit. It does not explain partial update semantics (whether unspecified fields are preserved), idempotency, permission requirements, or what response to expect. This is a significant gap for a mutation 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 two concise sentences, with the core purpose first and the rate limit as a useful addition. No wasted words, and the structure is clear and 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?

Given 8 parameters, no annotations, and no output schema, the description is notably incomplete. It fails to mention return values, error handling, permission needs, or update semantics, leaving the agent without critical context for correct invocation and expectation of results.

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

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

Schema description coverage is 100%, so all 8 parameters are already documented with descriptions. The tool description adds no extra parameter semantics beyond what the schema provides, meeting the baseline but not exceeding it.

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 'Update an existing project in Pylon' clearly identifies the verb (update), resource (project), and system (Pylon). It distinguishes the tool from siblings like pylon_create_project and pylon_delete_project by specifying 'existing project'.

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 'existing project' implies this tool is for modifications rather than creation, giving some context. However, it does not explicitly state when to use this over alternatives, nor does it mention any exclusions or prerequisites, leaving usage guidance mostly 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 provided, the description carries the full burden for behavioral disclosure. It mentions the rate limit (60 requests per minute), which adds some context, but it does not disclose required permissions, side effects, partial update behavior, or error handling for a mutating operation. This is insufficient for a tool that modifies 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?

Two sentences, minimal words, and directly front-loaded with the purpose. The rate limit is a useful extra detail. No filler or repetition, making it appropriately concise.

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

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

Despite full schema coverage, the tool is a complex mutation with 9 parameters and no output schema or annotations. The description lacks usage context, behavioral details, and any mention of return values or effects beyond 'update'. The rate limit adds a little, but the overall context is under-specified.

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 provides descriptions for all 9 parameters, and the schema description coverage is 100%. The description adds no additional parameter semantics beyond what the schema already offers, so it meets the baseline of 3 without needing to compensate.

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

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

The description clearly states the action ('Update'), the resource ('task'), and the system ('Pylon'), making it specific and unambiguous. It distinguishes from sibling tools like pylon_create_task and pylon_delete_task by using 'existing' to imply modification.

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 that this should be used to modify existing tasks rather than create or delete them, and no alternative tools are referenced. The rate limit is a constraint, not a usage guideline.

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