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

Annotations already declare this is a non-readonly, non-idempotent, non-destructive write, so the safety profile is covered. The description adds genuinely new behavioral facts: notes are appended (accumulative), auto-timestamped, and capped at 2,000 characters — a limit absent from the schema. It does not cover permissions or error behavior.

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

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

A single well-formed sentence that front-loads the action and appends the key constraint. No filler or restatement of the tool name.

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

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

An output schema exists, so return values need not be described, and annotations cover the mutation safety profile. What remains missing is minor: permission requirements and whether the contact must pre-exist.

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

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

Schema description coverage is 0%, so the description carries the burden, and it only partially does: it implies contact_id via "a contact's timeline" and gives a 2,000-character limit for text, but never documents either parameter by name or 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?

"Append a timestamped note to a contact's timeline" is a specific verb+resource with the mutation's effect stated plainly. It is clear, though there are no similarly-named siblings to differentiate it from, so it stays just short of a 5.

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

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

The description never states when to add a note versus another action (e.g. create_task or update_deal_stage), nor any prerequisites such as the contact existing. Usage is only inferred from the tool name and the phrase "contact's timeline".

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds one useful semantic detail beyond that — that low_stock_only compares against each item's reorder level. It says nothing about result size, pagination, or default behavior, but with annotations carrying the behavioral load a 3 is appropriate.

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

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

Two short sentences, front-loaded with the resource and then immediately the two usage modes; nothing is wasted. The opening fragment 'Stock levels.' is compressed to the point of being slightly cryptic, which keeps it from a 5.

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

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

An output schema exists, so return format need not be described. Combined with annotations and the two-mode usage guidance, an agent has enough to call it correctly. The only real gap is the no-argument default path, which is left implicit.

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

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

Schema description coverage is 0%, so the description must carry the meaning, and it does explain both parameters: sku selects a single item, low_stock_only=true filters to at-or-below-reorder items. It also clarifies the threshold semantics ('at/below their reorder level'), which the schema does not. It does not address SKU format or interaction between the two params, keeping it short of a 5.

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

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

The description names the resource (stock levels) and, through its two usage clauses, makes clear it retrieves inventory data by SKU or by low-stock filter. It lacks an explicit verb (the fragment 'Stock levels.' is terse), but the intent is unambiguous. The siblings are all unrelated domains (contacts, tasks, deals, orders), so no sibling differentiation is needed.

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 states two concrete invocation modes: pass a SKU to get one item, or set low_stock_only=true for items at/below reorder level. That is explicit guidance for both parameters. It stops short of a 5 because it never says what happens with no arguments (the default path) or whether the two modes can be combined.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false, and the description merely repeats 'idempotent' rather than adding context. It says nothing about side effects (notifications, status transitions), required permissions, or behavior when the task is already complete or does not exist.

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

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

A single short sentence, front-loaded with the operation and free of filler. It is arguably too terse given the missing guidance, but as a conciseness measure there is no wasted text.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. Still, for a mutation tool with a zero-documented parameter, the description omits what 'done' means, whether the change is reversible, and any error behavior for missing or already-completed tasks.

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

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

Schema description coverage is 0% and the single parameter task_id has no description. 'Mark a task done' only weakly implies the parameter is a task identifier, adding essentially no format, source, or validity detail beyond the schema's type.

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 ('Mark a task done'), which is unambiguous about the operation. However, it offers no differentiation from siblings like create_task, list_tasks, or update_deal_stage, so the agent gets no help distinguishing it from other task/deal mutators.

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

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

There is no guidance on when to use this tool versus create_task, list_tasks, or update_deal_stage, and no stated prerequisites (e.g., task must exist, must be in an open state). The description gives only what the tool does, never when or when not to reach for it.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds key behavior: dry_run default true, preview behavior, commit behavior (decrement inventory). This goes beyond annotations, though it doesn't mention permissions or error handling.

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

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

Front-loaded with purpose, then workflow. Three sentences, each earning its place. Minor punctuation issue (space before comma) but not distracting.

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?

Output schema exists, so return values needn't be explained. The description covers the critical dry_run behavior, default, and commit effect. For a 4-param tool with 3 required, it's mostly complete, though parameter details are sparse.

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

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

Schema coverage is 0%, so the description must compensate. It explains dry_run semantics well but doesn't add meaning for contact_id, sku, or qty beyond their names. Baseline 3 is reasonable given partial compensation.

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

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

States a specific verb+resource: 'Place a sales order for a contact.' Clear what it does. Doesn't explicitly distinguish from siblings like check_inventory, though the dry_run workflow provides some differentiation.

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

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

Explicitly describes the workflow: dry_run=true (default) returns a preview, confirm with the user, then call with dry_run=false. This is excellent when-to-use guidance and includes a recommended two-step process.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false), so safety is covered. The description adds a genuine behavioral rule beyond that — due_date must be YYYY-MM-DD and cannot be in the past — but says nothing about what the new task's identity/return looks like or whether contact_id must exist.

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

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

Two short sentences, correctly front-loaded with purpose before the parameter constraint. Every sentence earns its place, though there is no structure beyond the single constraint note.

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

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

An output schema exists so return values need no explanation, and this is a simple four-param creation tool. However, with 0% schema coverage the description leaves three of four parameters unexplained, which is a real gap for a mutation tool an agent must call with all four args.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it only documents the due_date format and validity constraint. The title, assignee, and contact_id parameters get no semantic explanation (e.g. whether contact_id must reference an existing contact), and the assignee enum is explained only by the schema.

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

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

States a specific verb and resource ('Create an open task for a contact') and the 'open' qualifier distinguishes it from siblings like complete_task and list_tasks. It does not name those siblings explicitly, so an agent must infer the boundary rather than being told it.

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 when-to-use or when-not-to-use guidance and does not reference any alternative tool. Usage is only implied by the verb 'Create' versus sibling names such as list_tasks or complete_task.

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 destructiveHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: it bounds the response (only the last 5 notes and last 5 orders, open tasks only), which tells the agent the payload is truncated and not a full history.

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, no waste. The payload contents lead, and the id-provenance instruction follows as a second short sentence.

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

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

An output schema exists, so return values need not be explained, yet the description still usefully signals truncation limits. Combined with annotations covering safety and the description covering input provenance, everything needed to call this correctly is present.

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

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

Schema description coverage is 0%, so the description must carry the parameter semantics, and it does: it identifies the parameter as the contact id, points to its source (search_contacts), and shows the expected format (C-1007). Only one parameter exists, so this is close to fully 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?

States a specific verb and resource ('Full view of one contact') and then enumerates exactly what the view contains (profile, deals, open tasks, last 5 notes, last 5 orders). This distinguishes it cleanly from the sibling search_contacts, which is a list/filter operation rather than a single-entity fetch.

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

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

Gives a concrete usage path: obtain the id from search_contacts and pass it here, with an example format (C-1007). It does not state when NOT to use it or name alternatives beyond the id source, but the context is unambiguous for a single-record fetch.

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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. Description adds that results are sorted by due date and that status defaults to open, which is behavioral detail not in the structured fields.

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

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

One well-structured sentence that front-loads the core action and then adds filters and ordering. 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?

Given that an output schema exists, return format need not be explained. The description covers purpose, default behavior, sort order, and filter formats, which is nearly complete for a 4-parameter read-only list tool.

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

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

Schema description coverage is 0% (no per-parameter descriptions), but the description compensates by clarifying assignee expected values (hamza|sana|ali) and due date format (YYYY-MM-DD). It does not explain limit or status parameters, leaving 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?

States a clear verb+resource ('List tasks') and adds useful scope ('default open ones'). Distinguishes from create_task and complete_task, though not from all siblings explicitly.

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

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

Implies usage by mentioning default filters and optional assignee/due date filtering, but does not explicitly say when to use this vs the sibling create_task or complete_task. Context is implied, not stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so safety and idempotency are covered. The description adds useful detail about what the summary contains (by-stage breakdowns, open total, upcoming closes), but it does not disclose things like refresh cadence, permissions needed, or result completeness.

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

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

The description is a single, front-loaded sentence that packs all key information without any filler. Every component listed (deals by stage, count + AED value, open pipeline total, next 30 days) earns its place.

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

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

Given the tool's simplicity (no params), existing annotations that cover safety behavior, and the presence of an output schema for return values, the description is complete enough. It clearly states the scope and dimensions of the summary.

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 baseline score is 4. The description does not need to explain parameters, and the empty schema is self-consistent.

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

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

The description names the specific resource (pipeline) and enumerates the exact metrics returned: deals by stage with count and AED value, open pipeline total, and open deals expected to close in 30 days. This is unambiguous and clearly distinct from all sibling tools, which deal with contacts, tasks, inventory, orders, and deal stage updates.

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

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

There is no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The description only states what it returns, not the context or conditions under which an agent should select it.

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

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

Annotations already declare this read-only, idempotent and non-destructive, so the safety profile is covered. The description usefully adds matching semantics (case-insensitive substring) and a hard result cap, but says nothing about ordering, pagination, or behavior on zero matches.

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

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

Two tight sentences, front-loaded with the searchable-field list, no filler. 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?

An output schema exists so return shape needn't be explained, and the description covers matching behavior and the result cap. Minor gaps (result ordering, empty-match behavior) remain for a search tool but are not blocking.

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

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

Schema coverage is 0%, so the description carries the load — and it does: it tells the agent what query matches against and that limit is capped at 50. Only the default of 10 is left to the schema.

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

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

States a specific verb (Find) and resource (contacts) plus the searchable fields (name, company, email, phone, city). An agent can distinguish it from siblings like get_contact or list_tasks, though it never explicitly frames itself as the attribute-based alternative to get_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 listed searchable fields imply the usage context (you have an attribute, not an ID), but there is no explicit when-to-use or when-not-to-use guidance, and the obvious alternative get_contact is never named.

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 declare that this is a non-read-only, non-destructive, non-idempotent, closed-world write operation. The description adds no behavioral context beyond that, such as side effects, permission requirements, 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?

The description is a single, front-loaded sentence with no wasted words. It communicates the core action efficiently.

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

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

Given the tool's complexity (two required parameters, one enum) and the absence of schema descriptions, the description is incomplete. It relies on annotations and the output schema for safety and return details, but fails to provide parameter semantics or usage context.

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

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

Schema description coverage is 0%, so the description must compensate by explaining parameters. It does not mention 'deal_id' or 'stage', nor does it clarify the enum values or their meanings, leaving the schema's enum as the only semantic aid.

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 clear verb ('Move') and resource ('a deal to a new pipeline stage'), making the action understandable. However, it does not differentiate from sibling tools, though none directly overlap with this 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?

No guidance on when to use this tool versus alternatives, prerequisites, or contexts. The description only states what it does, leaving the agent to infer usage from the name and schema.

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