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

No annotations exist, so the description carries the full burden. It discloses size limits (10 MB inline, 20 MB via source_url), that HTML renders isolated from the app, that replaces deletes the old file in one step, and a confidentiality warning — solid coverage. However it never says what is returned (an id? a url?) or what happens on failure, and it is a mutation tool with zero annotation backstop.

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 and mostly purposeful, but the size limits are restated (10 MB in the file sentence, again in the limits sentence, again for upload_link) and 'only when the person asks' appears twice, making the paragraph feel padded and harder to scan than it needs to be.

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 13-parameter, all-optional tool with no output schema, the description covers the decision tree well. The one real gap is the return value — an agent doesn't know whether it gets back an id it can later pass to replaces, which matters given replaces is central to the workflow.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra by explaining the interactions the schema can't: source_url as a substitute for text/base64, replaces requiring an id from start_task and only working on open tasks, and client_visible not applying to task files.

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?

Opens with a specific verb and resource (attaches a link or file to a project) and immediately enumerates the three intake modes: url+title for links, filename+text/base64 for files, source_url for remote files. An agent can tell it apart from upload_link, which is named as the alternative.

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

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

Explicit routing rules: which params to use per case (link vs file vs online file), when to use replaces instead of adding, when to set client_visible ('only when the person asks'), when not to use it at all (larger file → upload_link, secrets → never). Both alternatives and exclusions are 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?

With no annotations, the description carries the burden and discloses key behavior: @Name mentions notify the colleague, secrets are forbidden, and an existing note can be marked outdated with replacement text. It does not cover permissions, failure behavior, or visibility scope beyond 'colleagues should know.'

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 purpose is front-loaded in the first sentence, and each subsequent sentence adds a concrete constraint or workflow detail. It is slightly dense but not padded; every sentence serves a purpose.

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

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

For a 5-parameter write tool with no annotations and no output schema, the description covers content scope, safety constraints, notification behavior, and the obsolete-note workflow. It leaves repo/project/session precedence to the schema and does not describe permissions or return values, but those are minor relative to the core guidance provided.

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, but the description adds meaning beyond the schema: @Name inside text triggers a notification, and obsolete can be used alone or paired with replacement text. It reinforces that obsolete ids come from project_brief, which the schema also notes.

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 — saving a colleague-relevant note about a project — and defines the exact kinds of content it holds (access, convention, gotcha, location). This distinguishes it from task, comment, and document siblings without needing to name them.

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 a clear when-to-use rule: 'Only when the person asks or agrees,' and it implicitly excludes secrets/passwords/tokens. It does not explicitly name alternative tools like save_context or write_document, so sibling routing is left to inference.

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

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

With no annotations, the description does carry real weight: it discloses the confirmation-before-creation requirement, conditional client creation, team-level (not client) visibility, and that it returns a slug. It says nothing about permissions, duplicate rejection, or what happens when creation fails, so the mutation's risk profile is only partially covered.

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 short sentences, each carrying distinct information (action, visibility, preconditions, return value), with the action front-loaded. The telegraphic "The whole team (not clients)" sentence is the one rough spot in an otherwise tight definition.

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

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

For a 9-parameter mutation tool with no annotations and no output schema, the description covers the key behavioral hazards (confirmation flow, conditional client creation, return value) but leaves out permission requirements, side effects of template instantiation, and error behavior. Adequate, not complete.

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

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

Schema description coverage is 100%, so every parameter is already documented with examples and defaults. The description only restates that name, client, and lead should be confirmed, adding no syntax or format detail beyond the schema — 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?

States a specific verb and resource ("Creates a project") and adds that it can also create the client. The fragment "The whole team (not clients)" is ambiguous — presumably visibility/assignment scope — but the core action is distinguishable from siblings like update_project or use_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?

"Only when the person asks; confirm the name, the client and who leads it first" gives an explicit gating condition and a pre-call confirmation checklist. It does not name alternative tools (e.g. update_project for existing projects), but the when-to-use guidance 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?

No annotations exist, so the description bears the full load. It does disclose useful behavior: that a task can be unassigned (free) and that confirmation with the person is required before writing. It says nothing about duplicate handling, permissions, what gets created in response, or that "idea" tasks stay out of open tasks.

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 filler, with the core action first and the interaction rule second. The parenthetical assignment list is slightly dense but every clause carries meaning.

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

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

For a nine-parameter write tool with no annotations and no output schema, the description covers intent and confirmation but omits the behaviorally significant cases (idea vs. real work, recurring tasks, repo/session project resolution). Those are documented per-parameter, so the description is workable but thin relative to the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already explains repo, session, repeat, idea, and assignee semantics in detail. The description adds only the assignee framing ("free", "me", "for a colleague"), which the schema itself also states. Baseline 3 applies.

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

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

Specific verb and resource ("Adds a task to a project") plus the three assignment modes (free / me / colleague) that define what kind of task gets created. It implicitly separates itself from update_task and add_note, but never names a sibling to route the agent 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?

Gives a concrete precondition: "Confirm the title and who does it with the person first." That tells the agent when it may proceed and what must be settled beforehand. It stops short of naming alternatives (update_task, add_note, add_project) or when not to create a 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?

With no annotations, the description carries the full burden and discloses important behavior: this is an additive manual entry tool, only used on explicit user instruction, defaulting to the session's project and today. It also explains the date lower bound tied to the admin's reporting window and last_update, but it omits how duplicates, permissions, and the resulting record are handled.

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 definition is three focused sentences and front-loads the core action and key constraint ('Only when the person says so'). Every sentence adds useful context with no fluff.

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

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

For an 8-parameter, 1-required, no-output-schema tool, the description plus rich schema covers the essential behavior: manual-only use, default project/date, and date-range limits. The main remaining gap is that it does not point to edit_time for later corrections or describe error behavior when a date is outside the allowed window.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning: project defaults to the session's project, date defaults to today, and date is constrained by the team's reporting window. This goes beyond what the schema alone states for those optional fields.

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

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

The description gives a specific verb and resource: adds time for work the agent could not measure, with concrete examples like meetings, calls, and work away from the computer. It is clear what the tool does, but it does not explicitly contrast itself with the sibling edit_time 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?

It provides a strong explicit trigger: 'Only when the person says so.' The examples clarify when this manual-entry tool is appropriate, though it does not name alternatives such as edit_time for corrections.

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

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

With no annotations, the description carries the full burden and discloses important effects: @Name notifies the colleague, the team sees the comment on the update, the update author is notified, and clients see only their own comments. It omits permission requirements, failure modes, and whether comments can later be edited or deleted.

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 action and key side effects, and every sentence carries relevant information. The consent sentence is slightly awkward and dense, but overall it is compact and appropriately sized.

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

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

For a comment-writing tool with no annotations and no output schema, it covers the write effect, consent precondition, notification behavior, and team/client visibility. It is missing explicit return behavior, error cases, and permission details, but the rich schema descriptions reduce the need to repeat those fields.

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 useful semantics by explaining that writing @Name in the text notifies that colleague and that the update may belong to the user or a colleague. It does not add meaning for the agent or session parameters 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?

It states a specific action and resource: writes a comment on an update, with examples like answering a colleague's question or leaving a note. The resource is distinguishable from nearby tools such as delete_comment and add_note, but it does not explicitly name or contrast with any sibling.

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

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

It gives a consent-based precondition ('Only when the person asks for it and agreed on the text') plus example use cases, which implies appropriate usage. However, it does not say when to choose this over alternatives like add_note or edit_update, nor does it give explicit when-not-to-use 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?

Goes beyond destructiveHint=true by stating irreversibility explicitly ('It cannot be undone') and disclosing a permission nuance the annotation cannot convey: an admin can delete anyone's comment on an update, while otherwise only the person's own comment is deletable. Failure behavior (e.g., comment not found) is not covered, keeping it short of a 5.

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, none wasted, with the destructive action and its condition front-loaded. The nested parentheticals around the 'on' values make it slightly dense to parse but nothing is redundant.

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

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

With no output schema needed and full schema coverage, the description supplies the mutation semantics, irreversibility, ownership rules, and id provenance an agent needs to call this safely. Only the result/error shape is unaddressed.

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 real value by explaining where the 'id' originates and by tying the 'on' enum values to their behavioral difference (task = own only, update = admin can delete anyone's). The 'session' parameter is still 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 and resource (deletes a comment) plus scope: only the person's own comments, on a task or an update, with the admin exception for updates. This is precise enough to distinguish it from comment_update/add_note siblings without opening any schema.

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 an explicit gating condition ('only when the person asks, after telling them which comment it is') and explains where to obtain the id (start_task, list_tasks, project_timeline, last_update, with 'mine' marking ownership). Both when-to-use and the prerequisite lookup path are spelled out.

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

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

With no annotations, the description carries the full burden: it discloses the dual read/write nature (listing without id, mutation with id), the ownership constraint (only the person's own entries), the session-time exclusion, and the consent requirement. It doesn't state whether deletes are permanent or whether changes are reversible, which is the one behavioral trait left uncovered for a destructive-capable 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 core correction action and the add_time relationship are front-loaded, and every sentence carries information. It is slightly run-on with several clauses packed into the first sentence, but no waste.

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, no-annotation, no-output-schema tool, the description covers modes, exclusions, ownership, and consent. The main gap is the return/confirmation behavior for destructive deletes, which matters given the absence of any output schema.

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, but the description adds real value by explaining the id/no-id duality that governs the whole parameter set: without id, it lists the person's recent added time with ids and `days` controls the lookback. That interaction is not obvious from the schema alone.

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

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

The description opens with a specific verb and resource — 'Corrects time the person added (add_time)' — and enumerates the concrete operations (move project/day, change minutes or note, delete). It explicitly names and distinguishes the sibling add_time it complements, and clarifies the no-id listing mode, so an agent can identify the tool without opening the schema.

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 explicit routing to add_time (corrections vs. initial logging), names the alternative listing behavior when id is absent, states an exclusion ('time measured from sessions cannot be changed here'), and imposes a permission guardrail ('Only when the person asks'). When-to-use, when-not-to-use, and alternatives are all present.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses authorization limits, the need for consent, that delete is only for duplicates/mistakes, and that every change is kept in history with the reason. It also explains the required reason with an example.

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 purpose is front-loaded, and each sentence adds operative information: correction scope, history/reason requirement, authorization, and the rule against a second update. 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?

Given the 17-parameter mutation surface, empty annotations, and no output schema, the description supplies the critical behavioral context: authorization, consent, delete semantics, history, and correction vs duplicate-creation. The schema already documents all parameters in detail, so the description is complete enough for correct selection and invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds useful grouping and meaning beyond the schema by mapping corrections to summary, line kinds, time, day, split, and delete, though it does not add much for the target-selection 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 uses a specific verb and resource: it corrects or deletes an already-sent update, enumerating what can be changed (summary, lines, time, day, split). It also distinguishes correction from creating a new update with 'Never send a second update to fix one: correct 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?

It gives explicit when-to-use guidance: correct an update already sent, delete only if sent twice or by mistake, never send a second update. It also states preconditions clearly: only the author or admin, and only after the person agreed to the correction.

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, so the safety profile is covered and credit goes to added context. With no output schema, the description is the only source of return-value information, and it does enumerate the payload (last update, the 'since' moment for git log --since, open/new tasks, next_steps, day start), which genuinely helps an agent plan. It omits failure behavior when no project resolves, which keeps it from a 5.

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?

It is a single short sentence, so it is compact, but it is not front-loaded with what the tool does — the imperative is a usage cue rather than a purpose statement. Nested parentheticals ('since', for git log --since) and the dangling final clause make it harder to parse than its length suggests.

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 three-optional-parameter, read-only lookup with a fully documented schema, the essentials are close to covered: the schema itself explains the repo/project/session resolution precedence. What the description leaves unclear is the exact purpose framing and what happens when nothing can be resolved. Adequate minimum-viable coverage, nothing more.

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

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

Schema coverage is 100% and the per-parameter descriptions are already strong and actionable (repo = output of git remote -v, project = slug, session from the cemainou line). The description adds nothing about any of the three parameters; the mention of 'since' refers to a returned value, not an input, and could even be misread as a parameter. Baseline 3 applies.

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

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

The description never states an operation verb; it lists payload contents ('your own last update on the project, the moment to report from, your open and new tasks, and next_steps'), which lets an agent infer that this is a read that gathers reporting context. It does not name or distinguish itself from plausible siblings such as log_update, my_day, whoami, or project_brief. Adequate but the purpose must be reconstructed from the field 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?

'Call it first when reporting' is a real sequencing directive that implies when to use it, and it is the strongest routing signal here. However, the trailing clause 'Also when your work day started' is grammatically broken and reads as a second trigger of unclear meaning. No when-not-to-use condition and no alternatives are named, despite there being ~35 siblings.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds useful result-shape context (client, lead, git repo, last update) that annotations don't cover, but says nothing about ordering, limits, or what the archived default means.

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, with the result shape stated first and the usage rule second. Everything is front-loaded and earns its place.

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

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

For a zero-required-param read tool with fully documented parameters, this is close to complete: the description compensates for the missing output schema by naming the fields returned. Minor gaps are ordering and default archived 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 coverage is 100% and both parameters are documented there. The description adds no syntax or matching detail for search or include_archived, so baseline 3 applies.

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

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

States a specific verb (list) and resource (projects) and enumerates the fields returned: client, lead, linked git repo, last update. This distinguishes it from siblings like use_project, project_brief and project_context, though it doesn't explicitly name them.

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 selection rule: use it to find the project a piece of work belongs to when the git remote does not match one. That is real when-to-use guidance, but no explicit when-not or named alternative is given, so it stops short of 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 readOnly annotation covers the safety profile, and the description adds meaningful behavioral detail about note visibility: notes come only with the person's own tasks, and a free task's note appears only after it is taken. It does not describe result limits, ordering, or pagination.

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-loads scope options and filters before stating usage and note-access caveats. The sentences are dense but each carries relevant 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 read-only task listing tool with a fully documented schema and no output schema, the description covers the main use cases and the important note-visibility behavior. It leaves lower-level details like include_done, ideas scope, and repo/project/session precedence to the schema.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters. The description restates a few key filters and the default scope but adds little parameter semantics beyond what the schema provides.

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

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

The description clearly states that this tool lists tasks on team projects and specifies the default scope (mine), free tasks, and all open tasks. It does not explicitly name sibling tools like my_day or search, so the distinction relies on the reader inferring scope differences.

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 provides clear usage context: use it to show what is on a person's plate or what they could pick up. It does not state when not to use it or point to alternatives such as my_day or search.

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

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

With no annotations, the description carries the full burden and discloses important mutation behavior: confirmation is required, reported days are not rewritten, a limited estimated_minutes exception exists, and sensitive data/code must never be saved. It does not cover return behavior, error handling, auth, or rate limits, so it is strong but not exhaustive.

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 purpose is front-loaded, followed by confirmation requirements, overwrite rules, the estimated_minutes exception, the log_update exclusion, and the safety rule. It is dense but every clause adds routing, safety, or format 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 complex nested days array with no annotations or output schema, the description covers the key usage and mutation constraints an agent needs to call it correctly. It remains slightly incomplete because it does not describe the response or failure behavior.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-field constraints beyond the schema: a reported day without time may receive only date plus estimated_minutes, and today is rejected. It also clarifies that the day entries map to one update per past day.

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: saves the rebuilt history of a project, one update per past day. It also distinguishes the tool from log_update by stating that today is not accepted here and should use log_update instead.

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 says to call it ONLY after the person has seen the draft and confirmed it, and points to reported_days and next_steps. It also states when-not conditions: days already reported are not rewritten, except for the estimated_minutes-only case, and today must use log_update.

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

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

With no annotations, the description carries the full burden. It usefully discloses the confirmation gate and the prohibition on secrets/credentials/personal data/code, but it omits side effects such as merging into an existing day's update, internal/client visibility, and task/time side effects.

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

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

Two sentences, front-loaded with the action and scope, then the confirmation and privacy constraints. 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 schema is rich and covers the many parameters, but the description is thin for a 30-parameter mutation tool with no annotations or output schema. It covers the key confirmation gate but not broader workflow relationships to siblings such as edit_update, last_update, or task/time handling.

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

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

Schema description coverage is 100%, so all 30 parameters are already documented in the schema. The description adds only general content categories, not parameter-level semantics; 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?

States a specific verb ('Saves') and resource ('status update'), plus the scope ('since the last update') and content categories. It is clear, but it does not explicitly distinguish itself from edit_update or comment_update.

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 an explicit gating condition: 'Call it ONLY after the person has seen the draft and confirmed it.' This is clear usage context, but there is no when-not guidance or alternative-tool routing for editing or commenting.

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 a read-only tool, so the safety profile is covered. The description does add real behavioral context beyond that: today's result includes in-progress tasks and focus, while past days do not, and viewing a colleague requires permission you may not have. It still says nothing about result limits, aggregation granularity, or what happens when the requested day has no data — modest added value given annotations carry the rest.

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?

Compact, front-loaded with the payload description, then defaults, then the trigger phrase, then the alternative. The middle sentence packs three ideas with semicolons and is denser than ideal, but every clause carries information and nothing is 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?

With no output schema, the description carries the burden of describing return values and it does so by enumerating the fields returned, including the today-only extras. For a read-only, two-optional-parameter tool this is nearly sufficient; only edge cases (empty days, aggregation rules) are unaddressed.

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

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

Schema coverage is 100% and already documents both params with formats, so baseline is 3. The description adds semantics the schema does not: both are optional with stated defaults, and 'person' is constrained to colleagues whose hours you are permitted to see — a meaningful eligibility constraint beyond 'part of the name or email'.

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 precisely and enumerates what a 'day' contains: minutes worked, per-hour (0-23) and per-project breakdowns, tasks done, plus in-progress tasks and focus for today. It also distinguishes itself from the sibling that reports the day (last_update). The opening is a noun phrase ('One person's day') rather than a verb, which slightly blurs whether this is a query or a report, but the payload 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?

It states defaults (today, yourself), how to reach other data (date for an earlier day, person for a colleague whose hours you may see), gives the natural-language trigger ('what did I do today / on Tuesday?'), and explicitly routes an adjacent need to last_update. Nothing is left to inference about when to pick this tool.

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

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

With no annotations, the description carries the whole burden; it does disclose the read defaults (unread only, newest first) and that marking read is a side effect gated on the person having seen the item. It does not say whether marking read requires any authorization, whether ids are validated, or whether the call returns the notification list when mark_read is used, which is a real behavioral ambiguity for a tool that both reads and mutates.

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

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

Front-loaded with the resource and its contents, then defaults, then the write behavior and the caution — every clause carries information. The telegraphic style ("mark_read marks some (by id) as read") is dense but readable and wastes nothing.

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 four-parameter tool with no annotations and no output schema, the description covers defaults and both mutation modes adequately, but leaves the return shape of a notification and the list-plus-mark interaction unspecified. An agent knows when to call it, but not exactly what it gets back.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds loose framing ("some (by id)", "all of them", "newest first") but the schema already defines `all`, `limit`, `mark_read` and `mark_all_read` with equal or greater precision.

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?

It names a concrete resource (the person's notifications / "the bell") and enumerates what flows through it: tasks assigned, comments and mentions, morning summary, feedback answers. It also states the two modes bundled into the tool (list, plus mark_read/mark_all_read). It stops short of naming a sibling such as team_activity or my_day to contrast against.

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?

"Use it for 'what is new for me?'" gives a clear selection criterion, and "Only mark them read when the person has seen them or asks" is an explicit constraint on the mutating path. No alternative tool is named for the adjacent cases (e.g. project-wide activity), so the routing is not fully closed.

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?

readOnlyHint=true already declares this is a safe read, so the description does not need to restate that. It adds real context beyond the annotation: this is a one-call aggregation covering many entity types, contrasted with narrower siblings. It does not discuss size limits or pagination for such a broad aggregate, which is the one remaining gap.

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

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

Front-loads the content inventory, then the usage conditions and alternatives. The long enumeration of included entities is dense but every item maps to actual returned data, so it earns its space. Could be slightly tightened but is efficient overall.

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?

No output schema exists, so the description carries the burden of explaining return contents — which it does thoroughly via the entity enumeration. For a zero-required-param read aggregator with full schema coverage, this is nearly complete; only edge behavior (large projects, truncation) is unstated.

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

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

Schema description coverage is 100% and all three params (repo, project, session) are fully documented, including the precedence rule that session's project wins over repo. The description adds no parameter-level meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('get up to speed on a project' / project_brief) and enumerates exactly what it returns: description, repos, team, notes, documents, files, links, decisions, tasks, blockers, updates. This is far more specific than sibling project_context or project_timeline, so an agent can distinguish them without opening schemas.

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?

Explicit when-to-use ('for /brief or when starting work on a project') and names three alternatives with the exact condition each covers: project_context for the full context document, project_timeline for day-by-day history, read_document for a document's text. Nothing is left to inference.

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

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

With no annotations, the description carries full burden and does substantial work: it discloses the delta behavior ('with what changed since you last read it') and the no-document fallback returning cemainou/next_steps material. It omits what happens on an invalid repo/session value and does not state that reading apparently records a per-user read marker, which is an implicit side effect.

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?

Purpose and read-before-working guidance are front-loaded, and the write-path pointer comes last. The middle enumeration of document contents is long but is load-bearing, telling the agent what the returned reference covers.

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?

No output schema exists, and the description compensates by describing the return: the context document plus a change-since-last-read summary, or seed material when none exists. That plus the save_context pointer is everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so repo, project, and session are already documented including the precedence rule ('session wins over repo'). The description adds nothing about them, so the baseline of 3 applies.

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

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

Specific verb ('read'/'returns') plus a precisely identified resource: the project's context document at /ctx, enumerated by what it contains. It separates itself from save_context by naming that sibling as the writer, but leaves overlap with project_brief and read_document unaddressed.

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 lasting reference to read before working on it' gives a clear trigger condition (start of work on a project). It names save_context as the alternative for the write path and explains the fallback when no document exists, but never states when to prefer project_brief or read_document instead.

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 declare readOnlyHint=true, so the description adds genuine value: result ordering (newest first) and the visibility rule that logged minutes are team-visible but never client-visible. That last point is ambiguous in phrasing but is real behavioral context the schema cannot express; no note on result size or truncation beyond the limit param.

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 tight sentences with the payload description front-loaded and the sibling redirect parenthetical instead of a separate paragraph. The trailing sentence about logged minutes is slightly elliptical but still 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?

With no output schema, the description carries the return-shape burden and does so by listing the result sections and ordering. Nothing critical is missing, though it does not say whether an empty history or missing project is an error versus an empty list.

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

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

Schema description coverage is 100% and every parameter (days, repo, limit, project, session) is documented in the schema, including defaults and precedence for session vs repo. The description adds no parameter detail, so the baseline 3 applies.

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

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

States a specific resource and enumerates exactly what the call yields: recent updates newest-first, documents changed, contributors, and open blockers. It also names the sibling it is not (project_brief) so an agent can distinguish the two without opening either schema.

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?

"Use it for what happened, day by day, or to write a brief" gives an explicit use case, and the parenthetical routes the one-call overview case to project_brief. Both the when-to-use and the alternative are 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 already declare readOnlyHint=true, and the description adds genuine context beyond that: the returned version number is a concurrency token required by write_document. That is a behavioral contract an agent cannot infer from the schema. It does not describe pagination of the listing mode or what a missing document looks like.

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, both front-loaded with the operative information: what is read, then what must happen before writing. No filler, and the write-dependency is not buried.

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?

No output schema and no annotations beyond read-only, yet the description conveys the essential return contract (document with version) and the dual behavior of list vs. read. Minor gaps remain around the shape of the listing result and version-mismatch handling, but an agent can call this correctly.

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

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

Schema description coverage is 100%, so every parameter is already documented, including title-as-slug, session precedence over repo, and version-for-history. The description broadly restates the title-absent listing behavior and the version number rather than adding format or edge-case detail 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?

States a specific verb and resource ('Reads a project document') and enumerates what a document can be (brief, concept, decisions, status page). It also spells out the alternate mode — listing documents, files and links when no title is given — which no sibling tool duplicates.

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 an explicit sequencing rule: read a document before changing it, because write_document needs the version you read. That names the relevant sibling and the condition that links the two. It stops short of stating when to prefer list mode versus other listing tools like read_file or project_brief.

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 substantial behavior beyond the readOnlyHint annotation: images may be scaled down, text/files return inline, PDFs/videos/Office/large files return a 15-minute download link, and the agent should download via curl to a temporary folder outside the project. It also includes a prompt-injection warning about treating content as information, not instructions.

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 action and then layers in useful return-format and safety details. It is dense but efficient; every sentence contributes, though the long parenthetical could be split for readability.

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

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

Given there is no output schema, the description fully covers return behavior (inline content versus expiring download link) and operational guidance for downloads. It gives an agent everything needed to call the tool correctly and handle the result safely.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description only reinforces the id source; it adds no new semantic detail about the 'session' parameter or edge cases beyond what the schema provides.

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

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

The description states a specific verb and resource ('Read a file') and immediately explains the two scopes (task or project), which distinguishes it from sibling tools like update_file and read_document. It also clarifies what kinds of content it returns, making the tool's purpose concrete and scoped.

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 explains where the file id comes from (start_task / list_tasks / read_document), which is essential usage context. However, it does not explicitly say when to use read_file versus read_document or update_file, so there is a minor gap in 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?

The description restates the readOnly semantics already covered by readOnlyHint, but adds genuinely new context beyond the annotation: it works on closed tasks too, and it discloses the breadth of the returned payload. It does not mention pagination or any access restrictions, though for a read-only single-entity fetch that is a minor gap.

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

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

Two dense sentences with the core capability front-loaded and the routing/alternative guidance trailing. Every clause carries information — scope, use cases, exclusion, alternative — 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?

With no output schema, the description compensates by enumerating what is returned (details, steps, comments, files, history) and noting closed tasks are included. Combined with fully documented parameters and readOnly annotations, 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 description coverage is 100%, so both parameters (id and session) are already documented in the schema with examples and precedence rules. The description adds no parameter-level guidance, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read one task in full') and enumerates the scope it returns: details, steps, comments, files and history. It also differentiates itself from the related siblings by name, telling the agent to use start_task for working on the task and update_task for answering, so the agent can choose without opening a schema.

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?

Explicit when-to-use triggers are given (to see what someone wrote, after a notification, before answering with update_task), plus an explicit alternative (start_task) and even a behavioral exclusion ('do not open the task page in a browser'). Nothing is left to inference about when this tool is the right choice.

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, so the safety profile is covered; the description adds the data source (git) and, critically, the shape of the response since no output schema exists. It does not cover failure modes (e.g., no repo, unlinked project) or what /history rebuild implies operationally.

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

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

A single front-loaded sentence that leads with the imperative 'Call it first' and then enumerates returns. The parenthetical field list is dense but every item carries information an agent needs to interpret the response.

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

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

With no output schema and three optional parameters, the description usefully compensates by naming the returned fields and pointing at next_steps for follow-through. It could be more complete about behavior when no repo or project is resolvable, but the essentials for calling it correctly are present.

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

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

Schema description coverage is 100%, so all three parameters (repo, project, session) are already documented, including the precedence rule that the session's project wins over the repo. The description adds nothing about parameter precedence or fallback behavior beyond that, so baseline 3 applies.

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

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

States a specific verb and resource ('rebuild a project's history from git') and enumerates the concrete outputs (reported days, from, untimed_days, next_steps), so an agent knows what it gets back. It does not differentiate itself from nearby siblings such as log_history or my_day, which keeps it at 4 rather than 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?

'Call it first' gives explicit sequencing guidance, which is unusual and valuable for an agent planning a multi-step flow. It gives no when-not-to-use condition and names no alternative tool, so it stops short of 5.

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

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

With no annotations, the description carries the burden and does well: it discloses the human-approval prerequisite, the no-secrets policy, and optimistic concurrency ('nothing is overwritten'), which is exactly the kind of mutation risk an agent needs. It stops short of saying what the tool returns (e.g. the new version number) or what happens if base_version is stale, so it is not fully complete.

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 tight sentences with no filler; the two-mode rule is front-loaded, followed by the prerequisites and the concurrency guarantee. The telegraphic style ('Never secrets.') is efficient rather than vague.

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 mutation with no output schema and no annotations, the description covers mode selection, approval gating, secret handling, and conflict behavior, which is most of what matters. It omits return value and failure behavior on a stale base_version, a modest remaining 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?

Schema coverage is 100% with rich per-parameter descriptions, so the baseline is 3; the description adds real meaning by explaining the base_version 0 convention and tying the non-zero value to the version read via project_context. The remaining parameters (repo, agent, session, note) are left entirely 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 and resource (saves the project's context document) and immediately distinguishes the two modes of the operation: first version (base_version 0) vs a new version keyed to what was read with project_context. An agent can tell this apart from sibling tools like write_document or project_context without opening the schema.

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?

Explicit about the workflow gate ('Only after the person saw the text and said yes') and the constraint ('Never secrets'), plus the concurrency rule when a colleague saved a newer version. It also points to the sibling (project_context) that supplies the value for base_version.

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

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

No annotations are provided, so the description carries the disclosure burden. It usefully states the visibility scoping ("projects the person can see") and that results are short excerpts rather than full content, but says nothing about result limits, ranking, pagination, or minimum query length 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?

Three compact sentences: what it searches, when to use it, and what to do next. The coverage scope is front-loaded and every clause adds 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?

With no output schema, the description steps in to explain the return shape (matches with a short excerpt) and the follow-up path to full reads. For a 3-parameter search tool this is nearly sufficient; only result-count and pagination behavior are left unstated.

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

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

Schema description coverage is 100%, so all three parameters are already documented, which sets the baseline at 3. The description reinforces the optional single-project scoping but adds no syntax or format detail, and never mentions the repo parameter.

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

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

Names the specific verb (finds) and enumerates the exact resource types covered — tasks, documents, notes, updates, comments, files, links — plus the result format (short excerpt). This distinguishes it clearly from sibling readers like read_document and list_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?

Provides concrete example intents ("where did we decide X?", "was there a task about Y?") and routes follow-up work to start_task, read_document, or read_file. It does not contrast with structured alternatives such as list_tasks or project_brief, so the boundary is clear but not exhaustive.

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

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

With no annotations, the description carries the full behavioral burden and does well: it names the recipient (admins), the notification behavior ('told in the bell when it is resolved'), and the required user-confirmation step. It leaves minor gaps around privacy and failure handling, so not a 5.

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-loads the purpose and then gives constraints efficiently in three short sentences. The web-button analogy is helpful, though the description could be slightly tighter.

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

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

For a simple two-parameter feedback tool with no output schema, the description covers purpose, scope, recipient, follow-up notification, and the usage precondition. An agent has enough information to invoke 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 description coverage is 100%, so the two parameters are already fully documented in the schema. The description adds context about the feedback content but does not add syntax or meaning beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Sends feedback about cemainou itself') and clarifies the scope by excluding project feedback. The examples (bug, hard to use, idea) and analogy to the web Feedback button make the purpose 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?

Explicitly states the gating condition ('Only when the person asks') and a required workflow step ('show them the text first'). It also clarifies when not to use it by saying the feedback is not about a project.

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 only annotation is idempotentHint, so the description carries most of the burden; it discloses team-wide dashboard visibility and that empty text clears the focus, which are meaningful behavioral facts beyond the schema. It does not address permissions or whether an existing focus is silently replaced.

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, front-loaded with the action and its visible consequence. The clearing rule is slightly duplicated against the schema, but nothing is padded.

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 small 4-parameter tool with full schema coverage and no output schema, the description covers purpose, trigger, and clearing behavior. The parameter interplay (session wins over repo, project fallback) is left entirely to the schema, which is acceptable but is the remaining 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?

Schema description coverage is 100%, including the empty-to-clear semantics and the session-over-repo precedence, so the baseline is 3. The description's 'Empty text clears it' restates the schema rather than adding new parameter meaning.

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 ('Sets what the person is working on right now') and adds the visible effect (shown to the team on the dashboard). It implicitly separates itself from heavier logging tools via 'no full update needed', but never names a sibling tool outright.

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?

'Use it when the person starts on something new; no full update needed' gives a clear trigger condition and implicitly excludes the full-update path. It stops short of naming the alternative (e.g. log_update/update_task) or stating when not to use it.

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

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

With no annotations, the description carries the burden and discloses the real constraints: the client sees it read-only on the project page, a document is shared only in its current version, it requires a project visible to its client, and a task's files follow the task. Reversibility is implied via 'visible: false'. It stops short of stating failure behavior (e.g. unknown title) or confirmation of what changes on the project 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?

Front-loaded with the core action, then constraints, then the alternative tool. Dense and nearly waste-free, though the parenthetical '(a document only in its current version)' interrupts the flow and the sentences run long.

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?

No output schema exists, and the description covers the effects, preconditions, and the sibling alternative well enough to call correctly. It does not say what the response looks like or what happens when the title matches nothing, which is a modest gap for a mutation tool without annotations.

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

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

Schema description coverage is 100%, so all five parameters are already documented, including visible's true/false meaning. The description reinforces the visible:false semantics and the project-visibility precondition but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource ('Shows a document, file or link already on the project to the project's client, or hides it again') and covers both directions of the toggle. It is clearly distinguishishable from the sibling write_document/add_attachment, which are named as the wrong tool for creating new items.

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 gates usage: 'Only when the person asks', and gives the alternate path: 'To add something new for the client, use write_document or add_attachment with client_visible.' Both the when-to-use and the when-to-use-something-else are stated with the selecting condition.

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

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

With no annotations, the description carries the disclosure burden and does explain key side effects: the task is set in progress for the person, linked to this session, and its time counts on the task. It also notes project/session switching implications, though it does not cover permissions, error cases, or whether taking over another person's task requires explicit consent beyond the schema's take parameter.

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 action and uses the id/no-id distinction early. It is dense and slightly run-on in the first sentence, but every clause adds decision-relevant 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?

There is no output schema, so the description must explain return behavior; it does so by saying the no-id path returns open tasks to choose from and the id path returns the task with full context. It lacks error and permission detail, but it is otherwise complete enough for an agent to call 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 workflow-level meaning beyond the schema: id omission changes the tool into a chooser, session takes precedence over repo project, and session_project switching should happen only after asking the person.

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: 'Start working on a task from this session,' and explicitly distinguishes the two modes by id presence. It also names the sibling alternative read_task, so an agent can tell exactly what this tool does versus adjacent 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?

It gives explicit usage conditions: omit id to choose from open tasks, provide id to start the task, and use read_task instead if the person only wants to read without taking the task. The 'Follow next_steps' instruction also directs post-call 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?

Annotations only declare readOnlyHint=true; the description adds a genuinely non-obvious access model — work hours are team-visible, while a collaborator sees only their own hours and only the projects they are on. That permission-scoping insight is exactly the value-add the description should carry. It stops short of covering result shape or any volume limits, which keeps it out of 5 territory.

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: the first front-loads what the tool returns, the second delivers the access-model caveat. No wasted clauses, though the opening noun phrase lacks the verb that would make the intent immediately 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?

With no output schema and only a readOnly annotation, the description does the heavy lifting well: it enumerates the returned data and discloses the visibility rules. It is complete enough to call correctly, with the only real omission being whether results are scoped by recency/team size.

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 both `days` (1–14, default 1) and `person` (name/email substring) are already fully documented. The description's phrases 'updates from the last days' and 'each person's' loosely echo these params but add no syntax, format, or default detail, so baseline 3 applies.

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

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

The description enumerates the resource contents precisely — current focus, last-seen time, recent updates, open blockers — so an agent can picture the payload. It does not name a verb ('retrieve/list') and does not explicitly differentiate from lookalike siblings such as last_update or my_day, keeping it at 4 rather than 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?

Usage is only implied: the agent must infer this is the right call when it wants a cross-team snapshot rather than a single person's status. No alternative is named, and no exclusion (e.g. 'use my_day for your own view') is given, so it sits at minimum-viable.

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

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

With no annotations, the description carries the burden well: it discloses permanent deletion versus document archiving, permission rules, and task-open constraints. It stops short of covering failure behavior or response details, but the key mutation side effects are clear.

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-loads the operations and is information-dense with little waste. The main drawback is its long, complex sentence structure, which makes some constraints harder to scan.

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

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

Covers the key complexity for a mutation tool: destructive behavior, permissions, task status, and confirmation requirements. It leaves some parameter distinctions to the schema, but is otherwise complete enough 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 100%, so the schema already documents all parameters. The description reinforces title, role, and remove semantics, but largely repeats schema descriptions and does not add much for project/session/repo distinctions.

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 specific verbs and resources: renames, re-labels, removes; files, links, project documents. It distinguishes id-based file/link updates from title-based document updates, making the tool clearly identifiable 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?

Provides clear usage context, including that it should only be used when the person asks and after confirming. It also states permissions and task-status constraints, though it does not explicitly name alternative tools.

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

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

With no annotations, the description carries the burden and does well: it discloses the permission model, that stages and categories replace the whole previous list, and that archiving preserves updates, tasks and files. It does not say what failure looks like when the caller lacks permission, nor whether partial updates are atomic.

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?

Densely front-loaded with em-dash clauses; nearly every phrase carries scope or permission information. The punctuation-heavy run-on makes it slightly harder to parse than it needs to be, but there is little 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?

For a 13-parameter mutation tool with no annotations and no output schema, the description covers the consequential behaviors: permissions, replacement semantics, archive side effects, and the confirm-first norm. Remaining gaps are error/response behavior and how the project is identified, which the schema already handles.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: client accepts 'none' to make the project internal, follow means blockers and updates appear in the morning summary, and client_visible covers tasks plus client-shown documents. Identification params (project/session/repo) are left entirely 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?

Opens with a specific verb and resource ('Changes a project') and enumerates the exact fields it can modify, including archive/unarchive. This is clearly distinguishable from siblings like add_project or use_project without opening the schema.

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 explicit preconditions ('Only when the person asks; confirm the change first') and per-field permission gates ('only the project lead or an admin', follow is 'anyone in the team'). It does not name alternative tools for creating vs. switching projects, so routing to siblings is left implicit.

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

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

The only annotation is idempotentHint, so the description carries the behavioral burden and largely does: it discloses that comments are visible to colleagues and clients, that remove_files only works on files you added and only while the task is open, and that moving projects affects who stays assigned. It does not describe what the call returns or whether partial multi-field updates can fail halfway, which is the remaining gap for a 15-parameter mutation.

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

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

Front-loaded with the purpose, and every clause maps to a real capability among 15 parameters, so the length is defensible. The single dense paragraph with heavy parenthetical nesting makes it harder to scan than a short bulleted breakdown would be.

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 15-param mutation tool with no output schema, it covers the operation semantics, the ordering prerequisite (read notes first with start_task or list_tasks), and the destructive edge cases. Missing only return/error behavior and any note on multi-field atomicity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds a little framing (assignee "me" takes the task, status todo promotes an idea) but mostly restates semantics the parameter descriptions already state, such as the "none" sentinels and the check/uncheck step numbering.

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?

Opens with a specific verb and resource ("Changes a task") then enumerates the distinct mutation families it covers: edit, take, move, move project, remove files, assign, tick steps, comment. It distinguishes itself from siblings by name (add_attachment, start_task, list_tasks), so an agent can route without opening the schema.

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 explicit use-this-not-that routing: add_steps instead of rewriting notes when only steps are added, check instead of a comment for finished steps, add_attachment with replaces instead of remove_files for a swapped file. It also sets the consent condition ("Only when the person asked for it") on the riskiest 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?

With no annotations, the description carries the full burden and does it well: link is one-time, expires in 30 minutes, max 6 files, max 20 MB per file, and returns both a link and a curl command. These are exactly the constraints an agent cannot discover from the empty annotation set.

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 that front-load what the tool returns and the curl command before limits. Parenthetical file lists and multiple clauses make it slightly heavy, but every clause carries real 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?

Covers return shape, lifecycle, size/file caps and consent, which is enough for a tool with no output schema and all-optional params. It stops short of explaining how repo, session and project interact when several are supplied, which the agent must piece together from the schema.

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

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

Schema coverage is 100% and each parameter (repo, task, project, session) is already documented in the schema, including the task-vs-project fallback and session precedence. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a concrete verb and resource: it 'gives a one-time link to upload files straight onto a task or a project', and names the file kinds and the curl alternative. An agent can tell this apart from add_attachment because the upload happens out-of-band rather than in conversation.

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?

Explicit triggers ('any file larger than a few MB, or a file the person has on their device'), an explicit exclusion ('files do not travel through the conversation as base64'), and a consent gate ('Only when the person asks or agrees'). Nothing about when to prefer this over siblings is left to inference.

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

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

With no annotations, the description carries the full load and does well: it discloses that this is a stateful linkage whose effects persist ('this folder remembers it') and that future reports, tasks, notes, and time entries are rerouted. It stops short of stating whether a second call overrides the prior project or what happens if the project is unknown.

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 core action front-loaded and the session-handling caveat placed after. Phrasing is slightly informal ('and this folder remembers it'), but nothing is redundant.

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 2-parameter, annotation-free stateful tool with no output schema, the description covers action, effect, persistence, and the session/no-session branch. Remaining gaps — error behavior on unknown project and re-link semantics — are modest but real for a tool that mutates routing state.

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 genuine workflow meaning by explaining the session parameter's optionality in practice — pass it from the cemainou line, or if absent, repeat project on every later call. That clarifies the consequence of omitting session, which the schema does not.

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 — 'Links this session to a project' — and then describes the concrete downstream effect (reports, tasks, notes, and work time are routed there). It is distinguishable from read-only siblings like project_brief or list_projects, though it does not explicitly contrast itself with set_focus, the closest ambiguous neighbor.

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?

'After the person said which project the work is about' gives a clear trigger condition, and the second sentence covers the fallback path for agents that have no session id. There is no explicit when-not-to-use guidance (e.g., re-pointing an already-linked session), but the invocation context is clear.

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

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

With readOnlyHint=true already covering the safety profile, the description adds real value by enumerating what the call actually returns — identity fields, focus, and work-day start — which is otherwise undocumented since there is no output schema. It doesn't cover edge cases like an invalid or expired token, which keeps it short of a 5.

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

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

A single front-loaded sentence that leads with the subject (who is connected) and then enumerates the returned fields. No filler, no repetition of the tool name beyond what's needed to anchor meaning.

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

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

For a zero-parameter read tool with no output schema and only a readOnlyHint annotation, the description carries the right load by describing the returned payload. Minor gap: it doesn't clarify the format or scope of 'focused on' or 'work day started', which an agent may need to interpret the response.

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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly implies a no-argument call that reports on the caller.

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 precisely — the token owner's identity (name, email, role, timezone) plus their current focus and work-day start — which makes it clearly distinct from siblings like my_day or last_update. The verb is implicit ("Who is connected") rather than an explicit 'returns/identifies', but the intent 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?

Usage is only implied: an agent can infer it should be called to learn the current authenticated identity and focus state. There is no explicit when-to-use or when-not-to-use guidance, and no mention of how it differs from adjacent tools such as my_day which also surfaces day-level information.

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

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

With no annotations, the description carries the behavioral burden well: it discloses concurrency handling, client visibility, and a safety rule against secrets. It does not cover auth requirements, rate limits, or general success return behavior, so it is strong but not complete.

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 appropriately sized for an 8-parameter write tool with concurrency and visibility concerns. It is front-loaded with the core action and each sentence adds non-redundant operational guidance.

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 complex mutation tool with no annotations and no output schema, the description covers the critical workflow, conflict behavior, visibility, and safety constraints. The main remaining gap is that it does not describe the normal success response, which is not documented elsewhere.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful semantics beyond the schema for base_version conflict behavior and client_visible read-only sharing. It also reinforces that body must be the whole Markdown document and that an existing title creates a new version.

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: creates a project document or saves a new version of one. It distinguishes creation from updating and explicitly names read_document and share_with_client as related 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?

Gives clear when-to-use guidance: only when the person asks or agrees, after showing them the text or changes. It also explains the read-first workflow for updates and when to use client_visible versus share_with_client.

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