SUNAGO Matrix

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

Annotations already indicate this is a write operation, and the description adds useful context: the record is flagged as is_manual, status defaults to Draft, and it can be linked to a deal/project. However, it does not disclose what the response contains, whether related deal/project records are modified, or any side effects of creating the contract.

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

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

Three concise sentences with no filler. The core action is front-loaded, the key differentiator is stated clearly, and the linking guidance is in one final sentence. Every sentence contributes to correct tool selection and invocation.

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, the description covers the critical selection criteria and key field relationships. Since there is no output schema, it would be slightly stronger if it mentioned what the created record returns, but overall the description provides enough context for correct invocation.

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

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

Schema description coverage is 50%, so the description partially compensates by explaining the purpose of deal_id/project_id linkage and the default status. It does not clarify parameters like customer_id, reference_number, or contract_value beyond what the schema already says, leaving some ambiguity.

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

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

The description states a specific action ('Create a contract record') and clearly differentiates this tool from the signed-proposal/e-signature flow by mentioning the is_manual flag. It is distinct from sibling tools like contracts_get and contracts_update and from CRM create 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?

Explicitly states when to use this tool: for contracts agreed outside the offer/e-signature flow. It also tells agents that contracts from signed proposals are created by that other flow instead, preventing misuse. The instruction to link the contract to a CRM deal and/or project adds practical usage 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?

Beyond the readOnlyHint and idempotentHint annotations, the description reveals important behavioral details: RLS scoping, a hard limit of 200, and pagination semantics with has_more/next_cursor and the instruction not to count a page while has_more is true. This significantly helps the agent handle pagination correctly and understand access boundaries.

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 tightly packed sentences with no filler. The core purpose is front-loaded in the first sentence, and the second sentence delivers critical pagination guidance without redundancy.

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

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

The description is adequate for a read-only list operation with an output schema and safety annotations. However, the complete lack of semantic guidance for status, deal_id, and project_id filters leaves gaps in an agent's ability to construct precise queries or know whether filters are exact-match or combinable.

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

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

Schema description coverage is only 50%: limit, cursor, and offset have schema descriptions, but status, deal_id, and project_id lack any description in both schema and tool description. The description only repeats the limit cap and discusses response pagination fields, not the filter parameters, so it fails to compensate for the undocumented 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 states a specific verb and resource ('List contracts') and adds the RLS-scoped qualifier, making it clear this is a read operation on contracts. It does not explicitly differentiate from sibling tools like crm_get_contacts or contracts_create/update, but the resource name is distinct enough.

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

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

The description provides no guidance on when to use this tool versus alternatives such as contracts_create or contracts_update, nor does it mention exclusion conditions or preferred alternatives. The context of being a list operation is implied, but no explicit routing or comparison with siblings is offered.

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 meaningful behavioral context beyond the annotations: it lists valid status values and explicitly warns about the limited effect of setting Terminated. This is valuable because the annotations only say the operation is not read-only and not destructive. No contradiction with annotations exists.

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 compact sentences. The first states the core action, and the second delivers an important operational caveat. Every sentence earns its place, and the most critical guidance 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?

Given 11 parameters, 0% schema description coverage, no output schema, and sparse annotations, the description leaves too much unexplained. Only status semantics are addressed; required contract_id and the meaning of the many mutable fields are omitted, making the tool under-specified for an agent to use confidently.

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

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

Schema description coverage is 0%, so the description must compensate. It documents the status parameter's allowed values, but the other ten parameters (contract_id, title, deal_id, currency, end_date, etc.) receive no explanation beyond their names. This is a significant gap for an 11-parameter tool.

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

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

The description states the operation clearly: "Update fields on a contract." It uses a specific verb and resource, and the status documentation adds scope. It does not explicitly differentiate itself from contracts_create or contracts_get, but the intent is unmistakable.

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

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

The description provides a clear when-not and an alternative for one important edge case: setting status to Terminated does not run the termination workflow, so the UI should be used when notice periods or credit notes apply. It does not provide broader guidance on when to use this tool versus create/get variants, but the update semantics are 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?

Beyond the annotations, the description discloses important behaviors not implied by readOnlyHint or destructiveHint: it refuses duplicate emails/phones unless allow_duplicate is true, treats company as free text rather than a linked record, and explains that one contact can be referenced by multiple leads. This gives the agent a realistic model of the tool's side effects and constraints.

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

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

The description is long, but it front-loads the clear definition and each additional section addresses a real workflow concern: duplicate creation, deal/lead attachment, pre-checks, and list/collaborator semantics. It is slightly redundant with schema descriptions for company, list_id, and is_collaborator, and the ALL-CAPS directives are visually noisy, yet the structure is logical and purposeful.

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 17 parameters and no output schema, the description covers the essential edge cases: duplicate handling, lead/deal association, pre-creation lookup, and workspace-specific lists. It is complete enough to invoke safely; the only minor gap is that it never explicitly states what the tool returns, but the post-creation instructions imply the agent will know when creation succeeded.

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

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

With only 53% schema description coverage, the tool description compensates for the most meaningful parameters: allow_duplicate's refusal workflow, list_id's name-or-id resolution, company's non-relational nature, and is_collaborator's distinction between working relationships and sales targets. Some remaining parameters are self-explanatory or already documented in the schema, so it does not need to cover all 17 explicitly.

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 opening sentence gives a concrete verb-resource pair: 'Create a CRM contact: a named person, with their address, phone numbers and CVR/VAT number.' It also distinguishes this tool from crm_create_deal and crm_create_lead by explaining that a contact sits outside the pipeline and that deals or leads carry the contact via contact_id.

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

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

The description gives explicit workflow guidance: check crm_get_contacts before creating from a lead, and ask whether to attach the contact to a deal after creation. It names the exact alternative tools for attaching to deals and leads (crm_create_deal, crm_update_deal, crm_update_lead) and warns against creating duplicate contacts.

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

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

Annotations only indicate this is a mutating, non-destructive operation. The description adds meaningful behavioral context: lead_id is auto-set by Matrix on Qualified lead conversion, creating into a won stage immediately stamps the deal closed, and missing contact_id leaves the deal without a counterparty. This goes beyond what annotations provide.

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 front-loaded with the core definition, then efficiently explains each important parameter without redundancy. Every sentence adds value, from the counterparty requirement to the won-stage side effect, and the prose remains tight.

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 10-parameter create tool with no output schema, the description covers the essential domain logic, required relationship, and a caution about won-stage behavior. It does not mention the return value or every parameter, but enough context is provided for an agent to call the tool correctly in most situations.

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

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

Schema coverage is 50%, so the description carries meaningful weight. It clarifies the domain semantics of contact_id, lead_id, and status beyond their schema descriptions, explaining why they matter and how they interact. Some parameters like value and win_probability remain underexplained, but the most ambiguous ones are covered.

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 and resource: 'Create a CRM deal' with a definition of what a deal is (a named opportunity with value, stage, and close date). It also differentiates from related siblings by explaining that a deal is how a contact enters the pipeline and by referencing crm_get_deals for stage names.

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

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

The description gives practical guidance on when to set lead_id, warns that a deal without contact_id has no counterparty, and tells the agent to ask before creating a deal directly into a won stage. It does not explicitly contrast with crm_update_deal, but the usage context is clear enough for correct invocation.

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

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

Annotations already indicate this is a write operation and not destructive. The description adds that the follow-up is 'linked' to a lead/deal/contact, which implies a reference relationship, but it does not explain validation behavior, whether the referenced entity must already exist, or what the success response looks like. No contradiction with 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?

One concise, front-loaded sentence with no filler. It names the verb, the resource, and the relationship in a compact way.

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 straightforward create operation, the description plus schema is sufficient to invoke correctly: required fields are defined, optional parameters are described, and the tool's purpose is clear. It does not specify success response or reference validation, but these are not blocking for an agent making a create call.

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

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

Schema description coverage is 71%, so the schema carries most parameter documentation. The description adds little beyond the concept that the follow-up is attached to a lead, deal, or contact, which mostly maps to reference_type. With high schema coverage, 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 states a specific action ('Create') and object ('follow-up task') and explicitly says it is linked to a lead, deal, or contact. This clearly distinguishes it from sibling tools like crm_create_lead, crm_create_deal, and crm_create_contact.

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

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

The description gives clear context: this tool is for creating follow-up tasks attached to a CRM entity. It does not explicitly mention when not to use it or compare it with crm_log_activity, but the follow-up-task framing makes the intended use 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?

The description adds valuable behavioral context beyond annotations: it explicitly states the duplicate email/phone rejection rule and the allow_duplicate escape hatch. It also clarifies workspace scoping. It does not mention success responses or side effects, but the annotations already cover the safety profile.

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 filler. The main action is stated first, then the critical duplicate-handling behavior is front-loaded. 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 a create operation with 11 parameters and no output schema, the description is not complete. It does not explain what the tool returns on success, how conflicts beyond duplicates are handled, or how required fields like full_name factor into creation. An agent would still need to infer or discover the response shape.

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

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

With 11 parameters and only 36% schema description coverage, the description should compensate by explaining parameter meaning and relationships. It only clarifies the duplicate behavior tied to email, phone, and allow_duplicate. Many parameters such as value, source, company, and description receive no semantic guidance beyond their names.

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

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

The description states a specific verb ('Create') and resource ('CRM lead') and scopes it to the caller's workspace, clearly distinguishing this from sibling tools like crm_create_contact or crm_create_deal. The title and description align on the operation.

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

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

The description implies usage for creating a new CRM lead, which is reasonably clear from the resource name, but it does not explicitly contrast with alternatives or state when not to use it. There is no mention of prerequisites or exclusions beyond the duplicate-refusal behavior.

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 goes well beyond the annotations: it discloses that deletion is soft, retains the contact in the recycle bin for 30 days, is reversible via crm_restore_contact, requires admin privileges, and includes an explicit note about not asking for a confirmation phrase. This is rich behavioral context that substantially helps the agent.

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

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

Three concise sentences, each adding distinct value: the action and reversibility, the admin requirement, and the confirmation/communication guideline. The key verb and resource are front-loaded with no redundant or filler content.

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

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

For a single-parameter, no-output-schema tool, this description is complete. It covers what happens to the contact, how long, whether it can be undone, who is allowed to do it, and what to tell the user. An agent has everything needed to decide and execute 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?

Although schema description coverage is 0%, the single parameter contact_id is self-explanatory in context: the description's subject is 'a CRM contact', making it clear the parameter identifies which contact to delete. More detail about obtaining the id would help, but the semantics are not ambiguous.

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

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

The description clearly states the verb 'soft-delete' and the resource 'CRM contact', distinguishing it from a permanent delete and from sibling tools like crm_delete_deal and crm_delete_lead. It also explains the recycle-bin behavior, making the tool's purpose 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 gives clear context: it is for soft-deleting CRM contacts, is admin-only, and explicitly instructs that no confirmation phrase is required because the operation is reversible. It names the restore path (crm_restore_contact), though it doesn't explicitly contrast with specific sibling deletion 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?

Even though destructiveHint=true already flags destructiveness, the description adds substantial behavior beyond the annotations: the 30-day recycle-bin retention window, the restore path via crm_restore_deal, the admin-only permission requirement, and the no-confirmation/inform-user expectation. These details are not derivable from the annotations and meaningfully shape how an agent invokes and reports the action. The description is consistent with readOnlyHint=false and destructiveHint=true, so there is no contradiction.

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

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

Three sentences totaling about 50 words, with the core purpose front-loaded in the first sentence. Every clause carries information: definition, retention/restore, permissions, and reply guidance. There is no redundancy or filler.

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

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

For a single-parameter tool with no output schema, the description covers the essentials: effect, duration, undo path, permission gate, and expected reporting behavior. Minor gaps remain, such as behavior when the deal is already in the trash (which idempotentHint=false hints matters) and any cascade to related records like followups or contacts.

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

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

Schema description coverage is 0% for deal_id and the description does not explicitly document the parameter's format or source. The parameter name is largely self-explanatory and the description grounds it as 'a CRM deal,' so the gap is tolerable; however, a note that the ID comes from crm_get_deals or list_trash would have fully compensated for the missing schema documentation.

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

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

The description opens with a specific verb+resource pair, 'Soft-delete a CRM deal,' which precisely names the action and object. The soft-delete qualifier and the explicit mention of crm_restore_deal set it apart from the other crm_delete_* siblings that target different entities (contact, lead, followup) and from any permanent-delete operation.

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

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

The description gives clear operational context: it is admin-only, so agents know who may invoke it, and it specifies the conversational behavior ('no confirmation phrase is required - but still tell the user what you removed'). It does not, however, explicitly state when to prefer this over alternatives such as list_trash or a permanent delete, so it falls just short of a 5.

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

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

Annotations already mark destructiveHint=true, but the description goes further by disclosing that deletion is permanent, there is no recycle bin, and confirmation fields must never be filled by the agent on its own initiative. This is exactly the kind of behavioral context an agent needs for a destructive 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?

Two short, front-loaded sentences deliver the most critical information first: permanence, then authorization and human confirmation. Every clause earns its place, with no filler or redundancy.

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

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

For a destructive, single-resource tool with no output schema, the description covers everything an agent needs: irreversibility, admin-only restriction, and the human-in-the-loop requirement. The schema already provides field-level details, so nothing critical is missing.

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

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

Schema description coverage is 67%, and the confirm and confirmation_phrase parameters are already well described in the schema. The description mainly restates the human-confirmation policy rather than adding new parameter semantics; follow_up_id, while implied by the tool purpose, still lacks a schema description.

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

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

The description opens with 'PERMANENTLY delete a follow-up,' stating the exact verb and resource. The additional details about no recycle bin and irreversibility remove any ambiguity about the operation's nature, and it is clearly distinguishable from sibling delete tools like crm_delete_contact.

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 strong usage conditions: the tool is admin-only, requires explicit human confirmation, and is irreversible. It does not explicitly name a non-destructive alternative like crm_update_followup, but the conditions clearly communicate when deletion is and is not appropriate.

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?

While annotations mark the operation as destructive, the description adds the crucial soft-delete behavior: 30-day recycle bin retention, reversibility, an admin-only restriction, and a user-communication requirement. This goes well beyond the structured 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?

Two compact sentences lead with the core action, then add the key caveats (recycle bin, admin-only, confirmation behavior) with no filler or repetition.

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

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

For a one-parameter mutation with no output schema, the description covers the operation, side effects, reversibility, access restriction, and interaction expectations. Nothing essential is missing.

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

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

There is only one required parameter, lead_id, and the description does not explicitly document it beyond the implication that it identifies the CRM lead. The name is self-explanatory, but with 0% schema description coverage, some explicit mention of what lead_id refers to would have been slightly stronger.

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 first phrase 'Soft-delete a CRM lead' names a specific verb, resource, and operation type, and the recycle-bin detail distinguishes it from a permanent delete. It also aligns with the sibling crm_restore_lead, making the tool's role 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 explicitly says it is admin-only, states that restoration is possible via crm_restore_lead, and clarifies when no confirmation phrase is required. This gives an agent both a prerequisite and routing guidance versus alternatives.

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

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

Annotations already mark this as read-only and idempotent, and the description adds meaningful behavioral detail beyond that: RLS scoping, the pagination contract, and the specific has_more caveat. This lets an agent reason about result completeness and repeated calls without contradiction.

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

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

Three short sentences with the core purpose first, followed by the most important constraint and a practical warning. There is no filler 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?

For a read-only list tool, the description covers the correctness-critical behavior: scope, limit, pagination contract, and the has_more pitfall. The output schema handles return-value details, and annotations cover idempotence and read-only safety, so nothing essential is missing.

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

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

The input schema already describes all four parameters individually, so the description does not need to compensate. The description adds pagination context and a usage warning, but it does not materially extend the semantics of limit, cursor, offset, or search 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 opens with a specific verb and resource: 'List CRM contacts'. The RLS-scoped qualifier and the resource name clearly distinguish it from sibling crm_get_deals and crm_get_leads tools. An agent can identify what this tool does and what it operates on immediately.

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

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

The description gives actionable usage guidance about pagination: max limit 200, response shape with pagination.total/has_more/next_cursor, and an explicit warning not to count a page as complete while has_more is true. It does not name alternatives, but the resource distinction alone is enough to route picking this tool over sibling get 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?

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses important runtime behavior: default open-only filtering, terminal-status exclusion, pagination details, meta.scope_note, and the 200-item limit. It also warns against summing values across pages, which is critical behavioral context not available from annotations or schema.

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

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

The description is dense but every sentence carries operational value: scope defaults, user-communication requirements, pagination handling, and the explicit warning against partial-sum calculations. It is front-loaded with the most important behavioral fact and avoids filler.

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

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

Given the tool's complexity—scopes, pagination, row limits, and interaction with reports_get—the description is complete. The output schema exists, so explaining return values is unnecessary, and the description covers all key invocation concerns including how to communicate results to the user.

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 high at 83%, but the tool description adds meaningful semantics beyond the schema: it explains the default scope set, the distinction between archived/all for time-spanning queries, cursor-versus-offset behavior, and pagination constraints. The only minor gap is owner_id, which has no schema description and no description-level guidance, but the rest is thoroughly covered.

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

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

The description opens with a specific verb and resource ('List CRM deals') and immediately clarifies the RLS scoping and default open-only behavior, which precisely defines what the tool does. It clearly distinguishes this tool from sibling get tools by explaining scope semantics and pointing to reports_get for pipeline totals.

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

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

The description explicitly states when to use different scope values ('archived for deals that are won or lost, or all for anything measured over a period') and gives a direct alternative ('use the reports_get deal_pipeline report for pipeline totals'). It also instructs the agent to disclose scope and read meta.scope_note, leaving no ambiguity about when to use this tool versus others.

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

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

Annotations already declare this as read-only and idempotent. The description adds valuable behavioral context by disclosing RLS scoping and the concrete pagination contract: max 200, pagination.total, has_more, and next_cursor. No annotation contradiction exists.

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 concise sentences carry all essential information: the core action, scoping, filter capabilities, and pagination behavior. There is no filler or unnecessary 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?

For a read-only tool with an output schema and strong annotations, the description covers the main selection and invocation needs: resource, scope, filters, limit, and pagination shape. A minor gap is the ambiguous 'or' in the filter list, since it does not explicitly state whether filters can be combined, and the RLS acronym is not expanded.

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

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

The description summarizes the filter parameters as completion, assignee, or reference, which maps to completed, assigned_to, reference_id, and reference_type. However, with schema description coverage at 57%, it does not add much detail beyond parameter names, such as value formats, reference_type pairing semantics, or whether filters can be combined.

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 starts with a specific verb and resource: 'List follow-up tasks'. This clearly distinguishes the operation from the create/update/delete/restore follow-up siblings, and the 'RLS-scoped' qualifier plus filter list further clarifies exactly what the tool returns.

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: it is a scoped list operation with filtering and pagination. It does not explicitly name alternative tools or exclusion cases, but no sibling getter for follow-ups exists, so the implied usage is clear enough.

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

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

Annotations only convey readOnly and idempotent hints, so the description carries the full behavioral burden and does so richly. It discloses RLS scoping, the active-only default, the `meta.scope_note` field, the `pagination.total`/`has_more`/`next_cursor` response shape, and the critical warning not to summarize from a partial page.

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 longer than average but every sentence earns its place by covering a distinct operational caveat: conversion checking, default scope, scope selection, pagination, and counting rules. The core purpose is front-loaded, though the capitalization-heavy emphasis is slightly noisy.

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 7-parameter schema, output schema, and large sibling set, the description is remarkably complete. It covers the RLS context, the conversion edge case, the default scope behavior, how to handle archived records, and how to correctly count or paginate results. Nothing critical is left unexplained.

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

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

Schema description coverage is 86%, so the schema already documents most parameters and establishes a baseline of 3. The description adds meaningful decision guidance beyond the schema, especially around when to use `scope: archived` vs `all`, and reinforces the limit and pagination contract. It does not add value for every parameter, but the added semantics justify a step above baseline.

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

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

The description opens with 'List CRM leads (RLS-scoped)', a specific verb and resource that clearly distinguishes this from sibling tools like crm_get_contacts and crm_get_deals. The additional mention of `contact_id` and `converted_to` confirms it is about lead records specifically, not contacts or deals.

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

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

The description gives explicit when-to-use guidance: default to active leads, pass `scope: archived` or `all` only when the question concerns closed or historical leads, and check `converted_to` before offering to create a contact or deal. It also explains the pagination rules for counting leads, leaving little to inference.

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

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

Annotations already signal readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds the useful side effect that entries show up in the deal timeline, but does not disclose behavior around idempotency, permissions, or duplicate entries. This is adequate but not rich.

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 no filler. The core action is front-loaded, and the usage guidance and timeline effect are included without redundancy.

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

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

For a simple 3-parameter mutation with a schema that already defines required fields, enum values, and length constraints, the description supplies enough context to invoke the tool correctly. The main gaps are a full explanation of the undocumented parameters and any expected return/confirmation 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 0%, so the description should compensate for the undocumented parameters. It partially covers activity_type by listing note, call, meeting, and email, but omits the 'task' enum value and gives no detail about deal_id or description semantics, including the 4000-character limit.

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

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

The description states a specific verb ('Append') and resource ('activity log entry...to a deal'), and enumerates the supported activity types. Naming the deal timeline outcome also differentiates it from generic note/timelog tools among the siblings.

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

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

The description explicitly tells the agent to use this for the meeting-log primitive and explains the expected effect: the activity appears in the deal timeline. It does not explicitly state when not to use it or name alternatives, but the guidance is clear enough for an agent to select it appropriately.

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?

Beyond the annotations, the description adds meaningful behavioral details: the record must be soft-deleted and in the recycle bin, restoration is admin-only, and the operation fails if the record has been purged after 30 days. This gives an agent concrete expectations about preconditions and failure modes that annotations alone do not convey.

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 three short sentences with no filler. The core action is front-loaded, then the authorization constraint, then the failure condition. Every sentence contributes a distinct piece of 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 single-parameter restore operation with no output schema, the description covers purpose, prerequisites, authorization, and a key failure condition. It is complete enough for an agent to select and invoke the tool correctly without additional context.

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

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

With 0% schema description coverage, the description carries the parameter-semantics burden. It does not explicitly define contact_id, but it implies the parameter identifies a soft-deleted contact in the recycle bin and that it must not be purged. The schema supplies the required, type, and uuid format, so together the agent has enough understanding.

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

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

The description opens with a specific verb and resource: 'Restore a soft-deleted contact from the recycle bin.' It clearly differentiates this tool from sibling restore tools like crm_restore_deal and crm_restore_lead by naming the target resource, and it adds the recycle-bin scope that makes the action 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 gives clear context: it is for restoring soft-deleted contacts, requires admin privileges, and cannot succeed for purged records. It does not explicitly name alternatives or say when not to use it, but the resource-specific wording combined with sibling names provides enough directional guidance. 'Admin-only' is a strong prerequisite signal.

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?

Beyond the annotations, which already mark the operation non-read-only, non-destructive, and idempotent, the description adds concrete behavioral constraints: it is admin-only, acts on soft-deleted records, and fails if the record was purged after 30 days. This gives agents useful outcome expectations without contradicting the 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 uses three short sentences, leading with the core action and object, then supplying two high-value constraints. Every sentence adds information and none is wasted.

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

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

For a single-parameter restore operation, the description covers what it does, the required permission, and the key failure condition. The annotations supply idempotency and destructive-safety signals, and no output schema is provided, so no return-value details are expected.

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

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

The input schema only provides deal_id as a required UUID, with no parameter descriptions. The description compensates by making clear the deal is the soft-deleted object to be restored from the recycle bin, so the meaning of deal_id is inferable even though it is not explicitly restated.

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

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

The description opens with a specific action and object: 'Restore a soft-deleted deal from the recycle bin.' This clearly identifies the resource and distinguishes it from sibling restore tools for contacts, leads, projects, and tasks.

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 establishes the situation in which the tool applies: restoring a soft-deleted deal. It also adds an admin-only prerequisite and a 30-day purge limitation. It does not explicitly compare itself to sibling restore tools, but the deal-specific scope gives enough 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?

Beyond the annotations, the description adds valuable behavioral context: the operation is admin-only, and it fails on purged records older than 30 days. This clarifies auth requirements and failure conditions. There is no contradiction with the idempotentHint or destructiveHint 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 concise sentences with the action front-loaded and constraints added efficiently. Every sentence serves a purpose: the first states the operation and target, the second gives auth and failure information. No unnecessary 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?

For a single-parameter restore tool, the description covers the action, the object state, the authorization requirement, and the key failure boundary. It does not describe the success response, but with no output schema and a simple operation, the provided information is largely sufficient for correct invocation.

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

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

The schema provides lead_id as a required UUID but no description. The tool description adds meaning by clarifying that the ID must reference a soft-deleted lead in the recycle bin and that a purged record will cause failure. This compensates for the 0% schema description coverage.

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

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

The description states a specific verb and resource: 'Restore a soft-deleted lead from the recycle bin.' This unambiguously explains what the tool does and distinguishes it from crm_create_lead, crm_delete_lead, crm_update_lead, and the sibling restore tools for other entities.

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: use this tool to restore a lead that has been soft-deleted and is still in the recycle bin. It also gives an implicit boundary by warning that restoration fails if the record was purged more than 30 days ago, but it does not explicitly mention sibling tools such as list_trash for locating the lead or alternatives for active leads.

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?

Reveals important behaviors beyond the annotations: PATCH-like partial update semantics, sentinel values for removal, and the critical warning that owner_id refers to an employees.id, not an auth user id. This is exactly the kind of behavioral context agents need.

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?

Four dense sentences with no filler. The core action is front-loaded, followed by partial-update semantics, removal behavior, and id/list constraints. Each sentence contributes a distinct operational rule.

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 17-parameter mutation with no output schema, the description covers the non-obvious essentials: partial updates, removal sentinels, the owner_id domain distinction, and list_id lookup scope. Minor gaps remain, such as how to clear ordinary string fields, but the critical context for correct invocation is present.

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

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

With schema description coverage at only 35%, the description compensates for the most ambiguous parameters: list_id can be a name or id and is workspace-scoped, owner_id is an employee id, and is_collaborator: false removes the mark. Remaining fields are reasonably self-explanatory by name, and the global partial-update rule applies to all.

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

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

States a precise verb and resource: 'Update fields on a contact', and enumerates the contact-specific field categories (address, extra phone numbers, CVR/VAT, collaborator mark, list). This clearly distinguishes it from sibling update tools like crm_update_deal or crm_update_lead.

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

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

Provides strong operational context: it explains that only passed fields change, and gives specific removal semantics for list_id and is_collaborator. It does not explicitly name alternative tools, but the partial-update guidance makes the when and how 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?

The description adds useful behavior beyond the annotations, especially the partial-update semantics and the explicit statement that won/lost status changes trigger no invoice or project. The annotations already indicate non-destructive intent, and the description deepens that context without contradicting it.

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

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

The description is compact and front-loaded with the core action. Each sentence adds meaningful operational context: what the tool does, how partial updates behave, and what side effects do not occur.

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 ten parameters, weak schema descriptions, and no output schema, the description leaves meaningful gaps. It does not describe the return value, specify valid status values, or clarify ambiguous field formats, so an agent may struggle to construct a correct invocation.

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

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

Schema description coverage is only 20%, and the description does little to compensate for the undocumented parameters. It explains the update behavior generally but does not clarify status values, date formats, value semantics, or how owner_id, contact_id, or lead_id should be referenced.

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

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

The description states a specific verb and resource: 'Update fields on a deal.' It clearly targets deals rather than contacts, leads, or followups, but it does not explicitly contrast itself with sibling update 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?

The description gives clear operation semantics: only passed fields are changed and omitted fields retain their values. It also clarifies that moving to won/lost is a plain status change with no invoice/project side effects. It does not explicitly mention alternatives or when not to use the 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?

Annotations only indicate non-read-only and non-destructive; the description adds material side effects: completed: true stamps completed_at with the current time, and completed: false clears that stamp. It also clarifies partial-update behavior, going well beyond the structured 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?

Three compact sentences, with the main action first, then the special completion behavior, then the general patch rule. No filler or redundant restatement.

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 core mutation behavior, side effects, and patch semantics, which is sufficient for a 6-parameter update with one required ID. It does not describe return values or date formats, but absent an output schema these are minor for a straightforward patch 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?

With 0% schema description coverage, the description compensates for the completed parameter by explaining its boolean effect on completed_at. It also clarifies that all other fields are patched, but gives no individual semantics for title, description, assigned_to, or scheduled_date beyond their names and 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?

States a specific verb ('Update') and resource ('follow-up') and adds the close/reopen behavior via the completed flag. This clearly distinguishes the tool from crm_create_followup, crm_get_followups, and crm_delete_followup by operation.

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

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

Describes the two key usage modes (close with completed: true, reopen with completed: false) and the patch semantics for omitted fields. It does not explicitly name sibling alternatives or state when not to use this tool, but the context is clear enough for an agent to invoke it appropriately.

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 annotations only provide readOnly=false and destructive=false, so the description carries the full behavioral disclosure burden. It clearly reveals patch semantics ('never a replacement'), strict status validation ('rejected by the database, not silently ignored'), and nuanced contact linkage behavior including multiple leads pointing to one contact and null detaching. This is far more transparent than the annotations alone.

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 four sentences, each carrying a distinct behavioral fact with no filler. It front-loads the core purpose, then adds patch semantics, status validation, and contact relationship nuances in a logical order.

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

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

Despite having 10 parameters, no output schema, and sparse annotations, the description provides all critical invocation knowledge: partial update behavior, validation rejection, the duplicate-contact workflow, and null detachment. The only minor omission is return-value details, which are less essential for a mutation tool and are not required by the context signals.

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

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

With only 10% schema description coverage, the description compensates well for the key parameters: the general patch rule applies to every passed field, and status and contact_id get detailed semantics including null handling. The remaining params like email, phone, company, and full_name are self-explanatory from their names, but owner_id and value receive no additional context, so the compensation is strong but not complete.

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

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

The description opens with 'Update fields on a lead,' naming a specific verb and resource, and immediately differentiates this from a full replacement by explaining it is a patch. This clearly distinguishes it from sibling tools like crm_update_contact or crm_update_deal by specifying the resource as 'lead.'

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

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

The description gives explicit usage context for the contact_id parameter: use it when crm_get_leads reports a possible duplicate, and link the existing contact instead of creating a second record. It also warns that status must be a valid pipeline stage. However, it does not explicitly name alternatives for the general update case or state when not to use this tool, so it falls just short of exhaustive routing guidance.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive. The description adds a permission requirement but does not disclose side effects, duplicate handling, defaults, or response behavior. Some value beyond annotations, but limited.

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 no filler. The main purpose is front-loaded and the permission note is directly relevant.

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

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

Given 10 parameters, no output schema, and low schema coverage, this description is far too thin. It does not explain required inputs, expected outcomes, constraints, or how to interact with related HR tools.

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

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

Schema description coverage is only 20%, and the tool description mentions none of the 10 parameters. The agent receives no help understanding what full_name, role, employment_type, or the other fields mean beyond the sparse schema.

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

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

States a specific verb and resource: 'Create a new employee record.' This clearly distinguishes it from hr_update_employee and hr_get_employees, and the scope 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?

Provides only an authorization prerequisite ('HR permission required') but gives no guidance on when to use this tool versus alternatives like hr_update_employee. The usage context is implied by the name 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?

Beyond the readOnly and idempotent hints, the description discloses sensitive-field masking, a 500-row limit, the always-present pagination.total and has_more fields, and warns against a common headcount mistake. This is substantial behavioral context that annotations alone do not provide.

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

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

Three short sentences deliver maximum signal: the core purpose is front-loaded, followed by only high-value behavioral and pagination warnings. No filler or repetition.

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

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

The description covers the essential operational details: field masking, hard limit, pagination semantics, and the correct way to count headcount. Since an output schema exists, return-value details do not need to be repeated, and nothing critical is missing for an agent to call this 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 50%, and the description does not explain the search or department parameters. It does add useful pagination-related context around limit/offset, but that partly duplicates the schema's own limit and offset descriptions, and the undocumented filter parameters remain under-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 'List employees' with a specific verb and resource, making the operation unmistakable. It also distinguishes itself from sibling tools like hr_get_roles and the employee mutation tools by focusing on listing employee records.

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

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

The description gives clear context for when to use this tool: to list employees, with important pagination guidance about using pagination.total rather than page counts when has_more is true. It does not explicitly name alternative tools or exclusion conditions, but none are necessary given the distinct resource.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this read-only behavior. It adds meaningful context beyond the annotation: roles are workspace-scoped, come from Role Management, and super_admin has a special limitation even when listed. A small gap remains around the exact return shape, but for a zero-parameter list tool this is sufficient.

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

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

Three sentences, each earning its place: the first defines the action and source, the second links the result to related tools and warns about cross-workspace assumptions, and the third handles the edge case of super_admin. No redundant or filler content.

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 zero-parameter list tool, the description covers scope, source, related tools, workspace-specificity, and a special-case role. Nothing an agent needs to correctly invoke this tool is missing; the absence of an output schema is acceptable because the result is a straightforward list of role values.

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 description has no parameter details to add. The baseline for zero-parameter tools is 4, and the description correctly focuses on the result's meaning rather than input semantics.

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

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

The description clearly states the tool's function: listing roles defined in the caller's workspace. It names the specific resource (roles under Role Management in Matrix) and distinguishes itself from related HR tools by explaining its role in employee creation/updating.

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

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

The description explicitly tells agents when to use this tool: to discover valid role values for hr_create_employee and hr_update_employee. It also provides a critical when-not: never assume a role exists based on another workspace, and notes that super_admin cannot be granted through MCP.

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

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

Annotations already indicate this is a non-read, non-destructive mutation, so the bar is lower. The description adds meaningful behavioral context beyond the annotations: is_admin has consequences for deletion and recycle bin access, and weekly_capacity_percentage affects all resource and utilization calculations. It also clarifies partial-update semantics. No contradiction with 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?

Two sentences with no fluff. The action and partial-update rule come first, followed by targeted warnings about the two high-impact fields. 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?

Given the 11-parameter, no-output-schema update context, the description covers the partial-update contract and the two behaviorally significant fields. Remaining gaps, such as return value or permission requirements, are minor and not essential for a competent agent to invoke the tool correctly.

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

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

Schema description coverage is only 18%, so the description must compensate. It does so for the two least obvious parameters: is_admin and weekly_capacity_percentage. The remaining parameters are mostly self-explanatory by name or already documented in the schema, such as role and employment_type. Critical hidden semantics are covered.

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

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

The description clearly states a specific action and resource: 'Update an employee record.' It also adds the partial-update rule, which narrows the tool's behavior. It does not explicitly contrast with hr_create_employee or hr_get_employees, but the resource and action are unambiguous among siblings.

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

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

The description implies when to use the tool: to change an existing employee record. The partial-update statement ('Only the fields you pass are changed') is useful guidance. However, it does not name alternatives or state conditions where another tool should be preferred, leaving sibling differentiation to inference.

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

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

Beyond the readOnly and idempotent annotations, the description reveals important behavior: records are permanently purged after 30 days, access is admin-only, responses contain an exact pagination.total, and has_more controls termination. This is meaningful behavioral context that an agent cannot infer from the schema alone.

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

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

The description is compact and information-dense. It front-loads the core purpose, then adds access, retention, search, and pagination guidance without filler or redundant restatement of the schema.

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?

Even without an output schema, the description specifies pagination response behavior (`pagination.total`, `has_more`) and covers scope, auth, retention, search, and limits. The only lightly documented parameter is `entity_type`, but the enum and record type list make it sufficiently usable.

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

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

Schema coverage is only 50%, but the description compensates by explaining the purpose of `search`, the max `limit` of 500, and how to use `offset` with pagination. It does not explicitly describe the `entity_type` parameter, though the enum values together with the listed record types make the meaning reasonably clear.

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 and resource—'List soft-deleted records currently in the recycle bin'—and enumerates the exact record types covered: leads, deals, contacts, tasks, projects. It clearly distinguishes this tool from ordinary get/list tools because it specifically covers soft-deleted records in the recycle bin.

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

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

The description gives clear operational context: Admin-only access, use search for a specific deleted record rather than paging through the whole bin, and page with offset until has_more is false. It does not explicitly mention the restore siblings as the natural follow-up, but the internal usage guidance is solid.

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 only readOnlyHint=false and destructiveHint=false in annotations, the description adds crucial side-effect detail: generated @[Name](id) markup, recorded mentions, bell notifications, no notification for self-tags, and acceptance of inline markup. It also discloses permission requirements.

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 front-loaded with the core purpose and every sentence adds relevant operational detail. It is longer than minimal, but the mention/notification behavior justifies the extra length.

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

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

For a create operation with no output schema, the description covers the key behavioral requirements: target entity, mention mechanics, notifications, and permissions. It does not state what the tool returns, which is the main 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 schema describes entity_type and mention_employee_ids, and the description enriches mention_employee_ids with lookup guidance and notification behavior. It leaves entity_id somewhat implicit, but 'to a lead, deal, contact or task' plus the required entity_type makes the intended value inferable.

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

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

The description opens with 'Add a note to a lead, deal, contact or task', naming a specific action and resource. The title and sibling set (notes_delete/notes_update) make the create-specific scope unmistakable.

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

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

It clearly states when the mention parameter is appropriate and points to hr_get_employees for ID lookup, and notes the edit-rights prerequisite. It does not explicitly contrast with alternatives like notes_update or crm_create_followup, but the create semantics are 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?

Annotations only flag destructive behavior, but the description adds rich behavioral detail: deletion cascades to mentions, notes bypass the recycle bin, the action cannot be undone, only the author may perform it, and the agent must never self-confirm. These go well beyond what readOnlyHint/destructiveHint provide.

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 dense sentences with no filler. The first sentence front-loads the action, scope, and cascade effect; the second covers consequences and the human-in-the-loop guardrail. Every clause 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 destructive note-deletion tool, the description covers permanence, mention cascade, author-only authorization, no-recycle-bin behavior, and the critical human-confirmation rule. With no output schema, omitting return-value details is acceptable. An agent has the key information needed to invoke the tool correctly.

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

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

The schema already documents confirm, confirmation_phrase, and entity_type with meaningful descriptions, covering 75% of parameters. The description reinforces the human-confirmation constraint but does not add new meaning for note_id or entity_type beyond what the schema states. Note_id still lacks an explicit semantic description in both schema and description.

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

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

Description opens with 'PERMANENTLY delete one of YOUR OWN notes together with its mentions,' specifying a clear verb, resource, and scope. It also distinguishes itself from related note tools and restore tools by emphasizing irreversibility and author-only deletion.

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 communicates preconditions: only the author may delete, deletion is permanent, and human confirmation is required. It implies when not to use the tool (e.g., for recycle-bin recovery or for others' notes), though it does not explicitly name alternative sibling tools such as notes_update or restore 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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the description need not re-state safety. It adds useful behavioral details beyond the schema: newest-first ordering, mention markup format, plain_content flattening, and pagination fields ('pagination.total' and 'has_more').

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

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

Three sentences, each earning its place: scope and ordering, mention formatting behavior, and pagination limits. Information is front-loaded and there is no filler.

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

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

With an output schema present and full parameter coverage, the description covers the remaining practical concerns: sorting, markup interpretation, and pagination behavior. Nothing essential to correctly invoke the tool is missing.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters. The description adds context about the response and ordering rather than deeper parameter semantics, keeping this at the baseline 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?

Description uses a specific verb ('List') plus a precise resource ('notes on a lead, deal, contact or task') and clarifies ordering ('newest first'). It is clearly distinct from the sibling notes_create/notes_update/notes_delete tools and from other getters that target different record types.

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 makes the intended use obvious: retrieve notes attached to supported entity types. It gives clear context and scoping, though it does not explicitly state exclusions or mention alternatives, which is acceptable because there is no competing note-retrieval sibling.

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 reveals important behavioral details beyond the sparse annotations: the platform refuses edits on other authors' notes, and mentions are re-synced with specific side effects—first-time tags trigger notifications, dropped tags remove the mention, and already-tagged people are not re-notified. This is valuable non-obvious behavior that an agent could not infer from the schema alone.

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 with no wasted words. It front-loads the primary action and constraint, then uses the second sentence to explain the most complex behavior (mention re-syncing). It is dense but easily parseable.

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 4-parameter update tool with no output schema, the description covers the core decision points: who can edit, what happens with mentions, and what content replacement means. It lacks only minor details such as return/error behavior or explicit linkage between entity_type and note_id, but the schema covers the entity_type role. The description is nearly complete.

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

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

With only 50% schema description coverage, the description compensates strongly. It clarifies that note_id must reference one of the caller's own notes, that content is a full rewrite, and it adds rich semantics to mention_employee_ids by explaining notification behavior and how it interacts with inline mentions. This goes well beyond the schema's brief parameter descriptions.

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

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

The description states a specific action and resource: "Rewrite one of YOUR OWN notes." It also distinguishes itself by clarifying that only the author can edit a note, which separates it from notes_create, notes_delete, and notes_get. This is 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 description gives clear when-to-use context: rewriting your own notes. It also provides an explicit when-not-to-use condition: editing a colleague's note is refused. However, it does not name alternative tools such as notes_create or notes_get, so it falls just short of a full 5.

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

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

Annotations already flag destructiveHint=true, but the description adds critical context: permanence, no recycle bin, scope limited to the signed-in user's own notifications, and the human-confirmation gate. This goes well beyond the structured 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?

Three short, dense sentences with the critical permanence warning front-loaded, followed by the single vs batch distinction and the human-confirmation rule. No filler or redundancy.

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

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

The description plus the fully covered schema give the agent the scope, destructive nature, single/batch behavior, and human-authorization requirement needed to invoke the tool correctly. Error or return behavior is not described, but no output schema exists and it is not critical for a delete 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?

Schema coverage is 100%, so baseline 3 applies. The description confirms the single/batch split and the human-supplied confirmation rule, but this largely mirrors the schema's parameter descriptions rather than adding new semantic detail.

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

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

States a specific verb ('delete'), resource ('notifications'), scope ('signed-in user's own'), and permanence. This clearly distinguishes it from notifications_get, notifications_mark_read, notifications_send, and other delete tools in the sibling list.

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

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

Provides explicit operational guidance: single deletion by id vs batch requiring human-set confirm/confirmation_phrase, and an explicit never-fill-in restriction. It does not name sibling alternatives like notifications_mark_read, but the context for when to use this tool is clear.

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

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

Beyond the readOnly/idempotent annotations, the description reveals ordering (newest first), return behavior (unread_count alongside the page), pagination semantics (pagination.total, has_more, offset until has_more is false), and the maximum limit. This is useful behavioral detail the annotations do not provide.

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

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

Three concise sentences front-load the core purpose, then cover return value and pagination. Every sentence earns its place with no filler 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 has 7 optional parameters fully described in the schema and an output schema. The description supplies the missing behavioral context: scope, ordering, unread_count, and pagination. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining how to paginate with offset until has_more is false and emphasizing the max limit of 200, which reinforces the schema's parameter info with operational guidance.

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

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

The description states a specific verb and resource: 'List the signed-in user's own Matrix notifications, newest first.' It clearly scopes the tool to one's own notifications and explicitly says there is no way to read anybody else's, distinguishing it from any other notification or retrieval tool.

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

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

The description gives clear context: it lists the signed-in user's own notifications and notes that unread_count is included so a separate unread-count call is unnecessary. It does not explicitly name alternative tools or state when not to use it, but among the notifications siblings the usage context is clear.

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

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

Beyond the annotations, the description explicitly states that already-read notifications are left untouched, which aligns with and elaborates the idempotentHint. It also clarifies the auth scope ('signed-in user's own') and the all-at-once clearing behavior, adding meaningful 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?

Three short sentences deliver the core action, the two invocation modes, and an important edge-case behavior. The description is front-loaded and every sentence serves a purpose 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?

The description covers the key invocation modes and the idempotent behavior, which is sufficient for a simple two-parameter mutation. The only minor gap is that it does not explicitly state what happens when neither parameter is provided, but the 'or' phrasing strongly implies that one should be chosen.

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?

While the schema already covers both parameters at 100%, the description adds the 'or' relationship between notification_ids and all: true, implying these are alternative ways to invoke the tool. It also clarifies that already-read notifications are unaffected, which is useful behavioral meaning beyond the schema descriptions.

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

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

The description opens with a specific verb and resource: 'Mark the signed-in user's own notifications as read.' It clearly defines the tool's scope and distinguishes it from siblings like notifications_delete or notifications_get by focusing on the mark-read action.

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

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

The description gives clear context for when to use the tool: for the signed-in user's own notifications, with guidance on choosing between specific IDs or 'all: true'. It doesn't explicitly name alternative sibling tools or exclusions, but the intended use cases are clear enough.

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 all false, so they carry no behavioral signal; the description takes on the full burden and does so thoroughly. It discloses that employee IDs are resolved to logins, out-of-workspace recipients are refused, delivery is immediate, the notification is type 'custom', the sender's name is appended, and record links open on click. This is rich, accurate 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 front-loaded with the primary purpose and recipient semantics, and most sentences earn their place. The internal detail about type 'custom' and sender-name appending is useful but slightly dense; it could be tightened without losing value.

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

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

For a 7-parameter write tool with no output schema and non-informative annotations, the description covers the essential invocation path: recipient resolution, workspace restriction, and record linking. Minor gaps remain around error behavior, optional link parameter usage, and the meaning of priority/title/description, but the tool can be called correctly with this description.

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

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

With only 57% schema coverage, the description adds meaningful semantics for employee_ids by explaining lookup and workspace validation, and for reference_type/reference_id by describing how the link opens a record. However, it does not clarify the meaning of title, description, or priority beyond what the schema already provides, and the relationship between the optional link parameter and the reference parameters is not fully explained.

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

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

The description opens with a specific verb and resource: 'Send an in-app Matrix notification to one or more colleagues in YOUR workspace.' It clearly distinguishes this from system alerts and from sibling notification tools like notifications_get or notifications_delete by framing it as a person-to-person custom message.

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

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

It gives clear context on when to use this tool: sending person-to-person notifications to workspace colleagues. It also provides cross-tool guidance by directing users to hr_get_employees to resolve employee IDs, and states the workspace restriction. It does not explicitly name alternatives or exclusions, but the use case is well-scoped.

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

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

Annotations already indicate this is not read-only and not destructive; the description adds meaningful behavioral context by clarifying it only registers a reference and does not upload the file itself. This helps the agent avoid assuming storage behavior. It stops short of describing the response, but the core side-effect is well communicated.

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 filler: the purpose comes first, then the key prerequisite and required fields. Every sentence earns its place.

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

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

The description covers the essential invocation path—required fields and the storage prerequisite—so an agent could likely call the tool correctly. However, there is no output schema, optional parameter guidance is missing, and the description does not indicate what happens after registration, such as whether an ID or confirmation is returned.

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

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

Schema description coverage is 0%, so the description carries full responsibility for explaining parameters. It only clarifies file_path and file_name, leaving project_id, document_type_id, file_size, and mime_type unexplained. With six parameters, this is a significant gap.

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

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

The description uses a specific verb ('Register') and resource ('project document reference'), and the phrase 'already uploaded to storage' distinguishes this from an actual file-upload operation. This clearly separates it from sibling tools like projects_delete_document or projects_get.

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 should be used only after the file has been uploaded to storage by saying 'file_path (already uploaded to storage)'. However, it does not explicitly state when to use this tool versus alternatives like projects_delete_document, nor does it mention conditions around optional parameters like document_type_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?

Annotations only indicate generic read-only/destructive hints, so the description adds meaningful behavioral context by disclosing that this operation creates an assignment and rejects allocations over 100% capacity unless allow_overbooking is true. It does not describe error responses or effects on existing assignments, but the core validation behavior is usefully surfaced.

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

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

The description is compact and front-loaded: it states the action first, then the key allocation_type constraint, then the capacity rule. There is no filler, repetition of the title, or unnecessary 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?

The description captures the essential action and the most important validation rule, making a basic call plausible. But with 8 parameters, low schema coverage, and no output schema, it leaves missing details such as return behavior, end_date semantics, and the relationship between allocation_type and its numeric fields. It is adequate but not fully complete for an agent invoking edge cases.

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

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

Schema description coverage is only 38%, so the description must compensate for undocumented parameters. It partially does by naming allocation_type values and explaining the allow_overbooking bypass. However, it leaves gaps around how allocation_hours and allocation_percentage map to the two allocation types and what end_date/period means for the capacity check.

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

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

The description opens with a specific verb and resource, 'Assign an employee to a project,' which clearly expresses a team-member add operation. It is distinct from sibling tools like projects_update_team_member, projects_remove_team_member, and projects_add_document. The allocation_type mention reinforces that this is about staffing, not documents, pricing groups, or other project resources.

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

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

The description implies the primary use case: assign a new employee to a project. However, it does not explicitly state when to use this tool over alternatives such as projects_update_team_member, projects_remove_team_member, or resources_create_allocation. The agent must infer the correct tool primarily from the name and title.

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

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

The description explicitly discloses the most important behavioral trait: it replaces any existing pricing group for the member on the project. This goes beyond the annotations (readOnlyHint false, destructiveHint false) and warns the agent of an overwrite, though it does not cover prerequisites or reversibility.

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 concise sentence with the action front-loaded and a meaningful behavioral caveat added immediately. No redundancy or filler.

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

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

The core behavior and replacement semantics are covered, which is adequate for a simple assignment tool. However, it does not mention return values, whether the pricing group must already exist, or how this relates to the unassign sibling, leaving some context 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?

With only 33% schema coverage, only employee_id is documented. The description maps 'project team member' to employee_id and 'billing rate group' to pricing_group_id, but project_id remains implicit and no ID format or lookup guidance is given. It adds partial meaning but does not fully compensate for the schema gaps.

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 ('Put a project team member on a billing rate group') and resource, and the added behavior 'Replaces any existing group' distinguishes it from unassign/update tools. It does not explicitly name sibling tools, but the semantics are precise enough to avoid confusion.

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

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

Usage is implied rather than stated. The replacement behavior suggests this is the tool for assigning or changing a member's rate group, but there is no explicit guidance on when to use it versus projects_unassign_pricing_group or other project 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?

Even though annotations already provide idempotentHint, destructiveHint, and readOnlyHint, the description adds rich behavioral detail: it clears awaiting_manager_decision, status remains 'Completed', project stays archived, and auto_completed_at is preserved as history. It also discloses the permission requirement and the fact that this records a human decision, going well beyond the structured 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 four sentences, each earning its place: purpose, state-change details, alternative routing, and human-judgement warning. It is front-loaded with the main action and contains no filler or repetition.

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

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

For a single-parameter tool with no output schema, the description covers the action, the state transitions, the permission model, and the boundary against misuse. Nothing necessary for an agent to invoke this tool correctly is missing.

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

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

The input schema only says project_id is a string, with 0% schema description coverage. The description implies project_id identifies the auto-completed project being confirmed, but it never explicitly states that project_id is the ID of the project to confirm. The single obvious parameter reduces ambiguity, but the description does not fully compensate for the lack of schema-level parameter documentation.

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

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

The description names a specific verb ('Confirm'), a precise resource type ('a project the nightly automation closed for passing its end_date'), and clearly separates this from the sibling projects_reactivate. It also states the core outcome: recording a human judgement that the project is truly finished.

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

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

The description explicitly says when to use the tool ('Confirm that a project... really is finished'), when not to use it ('Never call this to tidy up a list'), and which alternative to choose ('Use projects_reactivate instead if the work is still running'). It also names the authorized actors, making usage conditions fully 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?

Goes well beyond the minimal annotations by disclosing the database trigger that keeps a project in Planning, the manager_id requirement tied to the nightly job and awaiting-decision lists, and the open_questions response behavior where missing fields are not errors but still need user follow-up. These are behavioral side effects an agent must know to invoke and follow up correctly.

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?

Despite being dense, the description is front-loaded with the one-line purpose and organized around REVENUE RULES and required-field calls. Each sentence adds necessary conditional or behavioral information, with no filler.

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

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

For an 18-parameter create with no output schema, the description addresses the hard parts: required fields (start_date, end_date, manager_id), status and budget_type domains, the revenue trigger, pricing_groups, and open_questions. Optional fields are left to the schema, which is acceptable given the schema already documents them.

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

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

The description adds substantial meaning: exact status values, budget_type default, conditional revenue requirements per Fixed vs Time/Time&Material, pricing_groups minimum structure, and revenue_ceiling as an optional cap. However, it states 'budget_type ... (default Fixed)' while the schema property says 'Required - ask the user rather than assuming,' an inconsistency that prevents a top score.

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

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

Starts with 'Create a new project,' a specific verb+resource statement that distinguishes this top-level creation tool from the sibling sub-resource creators such as projects_create_material and projects_create_risk. It then scopes the object with status, budget_type, and required dates, leaving no doubt about what is being created.

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

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

Provides clear context for when creation is appropriate: a project may be created in Planning before a price is agreed, and any status other than Planning requires revenue or pricing_groups depending on budget_type. It does not explicitly name alternatives or when-not-to-use cases such as projects_update, so it stops short of a 5.

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

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

The description makes the write action explicit and discloses an authorization requirement ('finance.create') that is not present in the annotations. The annotations already indicate readOnlyHint=false and destructiveHint=false, and the description does not contradict them. It does not mention response shape or idempotency, but the annotation coverage lowers the burden.

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

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

The description is two dense sentences with no filler. It front-loads the action and purpose, then gives the key parameter semantics and the permission requirement. 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 a create-style tool, the description covers the core business semantics, the distinguishing parameter behavior, and the required permission. The schema handles field formats and defaults for due_date and status. Minor gaps are the absence of return-value details and sort_order semantics, but an agent has enough to invoke this 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?

The description clarifies the conditional relationship between amount_type and amount_value, giving useful meaning to the core fields. However, the schema already documents most of this behavior, and the description does not explain project_id, sort_order, or description. With only 57% schema coverage, the description adds some value but does not fully compensate for the undocumented 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 states a specific action ('Add') and a specific resource ('a fixed-fee billing milestone to a project's billing plan'), and explains its business purpose: enabling a fixed-price project to be invoiced in instalments. The verb 'Add' clearly differentiates it from sibling tools that update, delete, or retrieve billing milestones.

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

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

The description gives clear context for when this tool is appropriate: adding instalment milestones to a fixed-fee project's billing plan. It also states a required permission ('finance.create'). It does not explicitly name alternatives or say when not to use it, so it stops short of a 5.

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

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

Annotations already indicate this is a mutating but non-destructive operation, and the description is consistent with that. It adds minor context by framing the action as adding a line item to a project, but it does not disclose behavioral details such as whether duplicates are allowed, how defaults apply, or what happens after creation.

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 concise and easy to scan, though its brevity comes at the cost of omitted useful 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?

For a create tool with 9 parameters, no output schema, no parameter descriptions, and only minimal annotations, one short sentence is insufficient. The description does not explain required fields, default behaviors, optional field semantics, or the expected result of 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?

Schema description coverage is 0% and the description mentions none of the 9 parameters. It does not explain the meaning of name, notes, status, agreement, assignee_id, is_billable, budgeted_cost, or markup_percentage, so the description fails to compensate for the complete lack of schema-level parameter documentation.

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 and resource: 'Add an external service line to a project.' This clearly distinguishes it from related project tools like material, risk, or pricing group creation, and from update/delete external service tools. It is not a pure tautology because it adds the 'line to a project' scoping.

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

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

The description gives no guidance on when to use this tool versus alternatives such as projects_update_external_service, projects_get_external_services, or other projects_create_* tools. An agent must infer usage purely from the tool name and sibling list.

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

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

The description goes beyond annotations by explaining real behavioral consequences: total_cost immediately consumes the material budget, is_billable and markup_percentage determine client charges, and non-billable lines still consume budget but earn nothing. It matches the mutation semantics of readOnlyHint=false and adds valuable side-effect detail.

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

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

Three sentences, with the core action front-loaded and every following sentence adding substantive financial or billing context. There is no fluff and no repetition of schema defaults.

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 10-parameter mutation tool with no schema descriptions and no output schema, the description leaves meaningful gaps: how unit_cost and quantity relate to total_cost, how markup_percentage is applied, and what the response looks like. It is adequate for tool selection and high-level input understanding, but not fully complete for precise 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?

With 0% schema description coverage, the description adds essential meaning for the least obvious parameters: total_cost, markup_percentage, is_billable, and workspace currency. It does not explain the relationship between unit_cost, quantity, and total_cost, or the exact markup formula, so it is not fully complete.

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

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

The description clearly states a specific action and resource: 'Add a material line to a project.' This distinguishes it from sibling tools like projects_update_material, projects_delete_material, and projects_get_materials. It also adds relevant domain context about material budgeting.

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 first sentence gives unambiguous usage context—use this tool to add a new material line to a project. It does not explicitly list alternatives or exclusions, so it misses the strongest 'when not to use' guidance, but the intended situation is clear.

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

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

Beyond the annotations, the description discloses a critical silent-failure mode: entering a rate in the wrong currency raises no error and only later causes incorrect revenue and margin. It also tells the agent that the response echoes meta.currency, which is useful behavioral context not present in the schema or 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 three sentences with no filler. It front-loads the core purpose, gives a concrete example, then adds the critical currency warning and response hint. 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 a simple 3-parameter create tool with no output schema, the description covers the key semantic trap (currency), indicates the response echoes meta.currency, and provides a realistic example. It could be slightly more explicit about the returned object or how this relates to projects_assign_pricing_group, but it is sufficient for correct invocation.

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

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

Schema coverage is only 33% (only hourly_rate has a description), so the description compensates by clarifying that hourly_rate is a SALES price in the workspace currency. It also helps with project_id and group_name by framing them in the context of creating a billing rate group on a project, though it does not detail their exact formats.

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

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

The description begins with a specific verb and resource: 'Create a billing rate group on a project', with a concrete example ('Senior Consultant' at 1450/hour). This clearly distinguishes it from sibling tools like projects_assign_pricing_group, projects_update_pricing_group, and projects_delete_pricing_group.

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

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

The description gives actionable guidance: check the workspace currency before entering a rate because a wrong currency silently produces wrong revenue and margin. It does not explicitly name alternative tools or state when not to use it, but the create semantics and currency precondition provide clear usage 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?

Annotations already signal the mutation is read-write and non-destructive; the description adds useful constraints such as allowed category/status values and the employees.id requirement within the workspace. It does not disclose side effects, duplicate handling, or other behavioral caveats, but the annotation safety profile lowers the burden.

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

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

Three short sentences carry only high-value information: the action, the exact allowed values for two constrained fields, and the lookup requirement for the foreign key. Nothing is padded or repeated.

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

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

The description is adequate for a basic call because required fields are apparent from the schema and the tool name, and the owner constraint is covered. It is not fully complete for nine parameters: it never explains the meaning of impact/probability, whether category/status are optional, or how project_id should be resolved to an existing project.

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

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

Schema description coverage is only 11%, and the description compensates for a few parameters by listing valid categories, statuses, and the responsible_owner lookup rule. Required project_id/title and the impact/probability scale remain underspecified, so the compensation is only partial.

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

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

The description opens with 'Log a new project risk,' which names a concrete action, the resource, and the 'new' state that distinguishes creation from the update/delete/get siblings. There is no ambiguity about what this 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 creation context is clear and the description adds a specific prerequisite: responsible_owner must come from hr_get_employees. It does not explicitly say 'use projects_update_risk for existing risks,' so it falls just short of fully explicit routing between sibling 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?

Annotations already indicate destructiveHint=true, but the description goes far beyond by disclosing the 30-day recycle-bin retention, cascading deletion of tasks, restorability, admin-only restriction, and the no-confirmation-phrase policy. This gives the agent an accurate behavioral model without contradiction.

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 deliver dense, useful information with no filler. The core behavior is front-loaded, and each clause adds a meaningful operational detail: soft-delete, retention, cascade, restore path, permissions, and user communication.

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

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

For a single-parameter delete tool with destructive annotations, the description covers the key operational context: what gets deleted, what happens to tasks, recovery options, admin requirement, and the required user-facing disclosure. No important behavior is missing.

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

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

There is only one parameter, project_id, and the schema provides its type. The description implicitly maps it to 'the project' being deleted but does not explicitly explain the parameter's meaning or format. Since the single parameter is self-evident from the tool name and title, this is adequate but not enhanced.

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

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

Description uses a specific verb and resource: 'Soft-delete a project', immediately distinguishing it from permanent deletion and from sibling tools like projects_restore. The recycle-bin and 30-day retention details further differentiate it from other delete 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?

The description gives clear context: admin-only, soft delete, non-permanent, and names projects_restore as the recovery path. It also instructs the agent to inform the user about which project and tasks were affected. It does not explicitly enumerate when not to use the tool, but the soft-delete framing makes the usage conditions 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?

The annotations already mark destructiveHint=true, but the description goes well beyond this by disclosing permanence, the invoiced-milestone refusal and its financial rationale, the required permission, and the hard rule that confirm/confirmation_phrase must never be agent-filled. This is exactly the behavioral context an agent needs before invoking a destructive 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?

Three sentences: the first states the action, the second explains a critical refusal condition, and the third states permissions and the human-confirmation rule. Every sentence carries essential information and the most important warning 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 destructive, permission-gated mutation tool with no output schema, the description covers permanence, refusal cases, permission requirements, and the human-in-the-loop constraint. No critical operational detail is missing.

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

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

Schema coverage is 67% and the schema already documents that confirm and confirmation_phrase must be human-supplied. The description adds important operational semantics by explicitly instructing the agent never to fill these on its own initiative, reinforcing the human-gated nature of the parameters beyond the schema text.

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

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

The description opens with 'PERMANENTLY delete a fixed-fee billing milestone', naming a specific verb, resource, and scope. It clearly distinguishes this from sibling tools like projects_update_billing_milestone and projects_delete_document by naming the exact object being deleted.

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

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

The description gives clear operational context: it is for deleting fixed-fee billing milestones, and explicitly states that invoiced milestones are refused. It also states prerequisites ('Requires finance.edit') and a required human confirmation step. It does not explicitly name an alternative tool for editing rather than deleting, but the usage boundary is otherwise 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?

Beyond the destructiveHint annotation, the description discloses that deletion is permanent, that the file remains in storage, and that the operation requires explicit human confirmation — 'never fill in confirm/confirmation_phrase on your own initiative.' This is exactly the behavioral context an agent needs.

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

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

Two dense, front-loaded sentences with no filler. The most important constraint (permanent deletion) comes first, followed by the storage caveat and the human-confirmation requirement. Every clause 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 destructive reference-removal tool, the description covers the core consequences and the mandatory safety condition. It omits details like error behavior or what happens if the document row does not exist, but nothing essential is missing for selecting and invoking the tool.

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

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

Schema coverage is 67%, and the description meaningfully reinforces the two confirmation-related parameters by forbidding the agent from supplying confirm or confirmation_phrase autonomously. It does not add detail about document_id, but that parameter's purpose is already evident from the tool's name and format.

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

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

The description states a precise action and resource: 'PERMANENTLY delete a project document ROW.' It goes beyond the name by clarifying the scope and its boundary ('the uploaded file itself stays in storage'), which distinguishes it from deleting the file or deleting an entire 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 gives clear operational context: this tool only removes the reference and does not free storage, so an agent can infer it is for reference removal rather than file deletion. It does not explicitly name an alternative tool or state a when-not-to-use condition, which prevents a 5.

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

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

Beyond the destructiveHint annotation, the description adds crucial behavioral context: the deletion is permanent, cannot be undone, lowers external cost, and requires explicit human confirmation. It explicitly instructs the agent never to populate confirm/confirmation_phrase on its own, which is essential for safe invocation.

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

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

Three short sentences, each carrying distinct and necessary information: what is deleted, the irreversible consequence and cost impact, and the human-confirmation requirement. No filler or redundancy.

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

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

For a destructive tool with one required parameter and no output schema, the description plus input schema fully cover what an agent needs: what is deleted, the irreversible nature, the required confirmation behavior, and the identifier parameter. Nothing critical is missing.

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

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

The schema already documents external_service_id, confirm, and confirmation_phrase reasonably well. The description adds important operational semantics by clarifying that confirm and confirmation_phrase must be supplied by the human, not the agent, and that the delete targets an external/subcontractor service line.

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

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

The description states a specific verb and resource: permanently delete an external/subcontractor service line from a project. It clearly distinguishes this from sibling tools like projects_update_external_service or projects_create_external_service by focusing on irreversible deletion.

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

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

The description gives clear context for when this tool applies: deleting an external service line from a project. It does not explicitly name alternatives or exclusion conditions, but the purpose statement is unambiguous enough for an agent to select it correctly among the sibling delete/update/create 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?

Annotations already mark destructiveHint=true, but the description goes well beyond them: it discloses irreversibility, that materials do not go to the recycle bin, that project material cost is lowered, and crucially that the human, not the agent, must supply confirmation fields. This is rich behavioral context that meaningfully affects how an agent should plan and invoke the 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 short, front-loaded with the key action and consequences, and every sentence earns its place: scope, irreversibility, recycle-bin behavior, and the human-confirmation rule. No wasted words.

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

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

For a destructive tool with no output schema and only three simple parameters, the description covers the essential context: what is deleted, the permanent consequence, and the mandatory human-in-the-loop confirmation. It does not mention what happens if the material_id does not exist or whether deletion is idempotent, but these are minor for a tool whose safety-critical aspects are already well covered.

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

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

Schema description coverage is 67%: confirm and confirmation_phrase already have explicit descriptions in the schema, and the description reinforces the human-only rule. The remaining parameter, material_id, is not described in the schema, and the tool description only indirectly clarifies it via 'delete a material line from a project'. The description adds safety emphasis but no substantial new parameter-level 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 states a specific verb ('delete'), a specific resource ('material line'), and a scope ('from a project'). It also emphasizes 'PERMANENTLY' and 'cannot be undone', clearly distinguishing this destructive operation from soft-delete/restore siblings. This leaves no ambiguity about 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 provides explicit invocation guidance: use only with explicit human confirmation, and never auto-fill confirm/confirmation_phrase. It makes clear this is a permanent act on a material line, not a reversible soft delete. However, it does not explicitly name alternatives (e.g., updating the material instead of deleting) or state when not to use it beyond the human-confirmation requirement, so it stops short of a full when/when-not comparison.

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