FrameOn — Agentic Project Management

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

The description goes beyond the readOnly/idempotent annotations by disclosing the 25,000-character truncation, the explicit response flag, and the required behavior (tell the person instead of reasoning as if the full text were present). It also discloses the context cost of browsing page by page. Annotations are consistent with the description.

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: purpose, truncation caveat with required action, and workflow warning. Each sentence adds a distinct piece of information and the most important usage constraint is front-loaded.

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

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

For a read-only, two-parameter tool with no output schema, the description is complete: it covers what is returned, the edge case (truncation), how to position it in a workflow, and when not to use it. No missing information prevents an agent from invoking it correctly.

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

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

Schema coverage is 100%: both project_id and document_id already have descriptions, so the description adds no parameter-level meaning beyond 'by id'. Baseline 3 is appropriate because no parameter clarification is needed beyond the schema.

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

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

The first sentence names a specific verb ('Reads'), a resource ('one document or Wiki page'), and the identifier ('by id'), making the operation unmistakable. It also says 'in full' and later qualifies with the 25,000-character truncation, giving a precise contract.

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 explicitly tells the agent to call this only after search_documents or list_documents_brief have pointed at the right page. The final sentence draws a clear when-not boundary ('not a way to browse') and warns about context burn, so there is no ambiguity about its role.

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

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds valuable behavioral context: results are filtered by token role so an empty result means 'nothing you can see', not necessarily 'nothing exists'; it defaults to active alerts only; and it intentionally cannot resolve/dismiss alerts. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose, then defaults, then caveats in a 'Two things worth knowing' format. Every sentence earns its place; the length is justified by the useful behavioral nuances and no redundant filler is present.

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 listing tool with six parameters and no output schema, the description provides the essential context: the kind of alerts, the response element fields, permission-based filtering, and non-mutability. Minor gaps remain for `sinceDays` and `alertType` value semantics, but the overall picture is clear enough for reliable invocation.

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

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

The input schema covers only one of six parameters (17%), so the description carries some burden. It does clarify the default status behavior ('Defaults to active alerts only') and hints at the alert fields returned, but it leaves `limit`, `sinceDays`, and `alertType` semantics to the schema. Since two parameters have enums and are self-explanatory, the gap is moderate.

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: 'Lists the risk alerts this workspace raised for the project on its own', followed by concrete examples of alert types. This clearly separates it from sibling tools like get_project_structure, get_task, or get_task_stats because it is exclusively about computed risk alerts.

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 an explicit when-to-use signal: 'the fastest way to answer "how is this project doing" with evidence instead of impression.' It also provides a clear when-not: 'you cannot resolve or dismiss an alert through this connector — that stays with a person in the UI, on purpose.' No sibling alternative is named, but none of the siblings serve the alert role, so the guidance is still strong.

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

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

Beyond the read-only/idempotent annotations, the description discloses meaningful behavior: the briefing is assembled raw from workspace records, not summarised; confidential memories are deliberately excluded; Wiki content appears only as titles and IDs. This gives an agent accurate expectations about output nature and limitations.

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

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

The description is front-loaded with the core purpose and immediately states the primary usage rule. It is somewhat longer than strictly necessary, with motivational context about shared memory, but each sentence carries practical information about content, confidentiality, or related tools.

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

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

For a tool with no output schema, the description adequately explains what the returned briefing contains, its format, its limitations, and how to follow up. Combined with the fully described input schema and safety annotations, nothing essential is missing for correct invocation and interpretation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level meaning beyond what the schema already provides for project_id and max_items, but it also does not need to since both parameters are fully documented in the schema.

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

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

The description states a specific verb and resource: 'Returns everything this project knows about itself as one markdown briefing', and enumerates the exact contents (decisions, conventions, Wiki, risks, work in flight). This clearly distinguishes it from siblings like get_project_alerts or get_project_structure.

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: 'READ THIS FIRST, before you touch the project's code or answer a question about it.' It also names alternatives and conditions: call get_document_full_content for relevant Wiki documents, and save new knowledge with save_classified_memory. No usage question 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?

The annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds valuable behavioral context on top: the hierarchy is free-form, any task type may parent any other, and unusual shapes are team choices, not errors to correct. This prevents the agent from misinterpreting returned data and trying to 'fix' it. No contradiction with annotations.

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

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

The core function is front-loaded in the first sentence, with usage guidance and caveats following in a logical order. It is longer than minimal, but every sentence earns its place: the free-hierarchy caveat and the create_task workflow note are both high-value, not 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 carries the burden of explaining what the tool returns, and it does: hierarchy, children, counts, progress, and optional deeper task levels. It also covers the important data-model caveat. It stops short of describing exact response shape or pagination, but for a read-only hierarchy tool the given context is strong.

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 parameters are already documented. The description adds real semantic value by explaining exactly when include_tasks matters ('when you need the level below stories') and by clarifying the project_id role implicitly through the hierarchy context. It does not, however, address the schema's odd note that a required project_id can be 'omitted once'.

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

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

The description names a specific verb ('Returns') and a specific resource ('the project hierarchy'), and lists concrete contents: epics, children, counts, and progress. It also explicitly carves out its uniqueness ('the ONLY tool that reports per-epic numbers'), distinguishing it from sibling tools like list_tasks and get_task_stats.

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: 'Call it before create_task' to determine the proper parent, and tells the agent when to pass include_tasks=true. It also asserts exclusivity ('the ONLY tool that reports per-epic numbers'), which tells the agent not to look for this data elsewhere.

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

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

Annotations already mark this read-only and idempotent, and the description adds meaningful behavior beyond that: it explains the visibility-dependent membership logic, enforces that only returned ids are valid assignees, and notes one project per call. These are non-obvious traits an agent needs before invoking the tool.

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

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

Three sentences with no fluff: purpose is front-loaded, the membership rule follows, and the actionable guardrail comes last. Every sentence earns its place, and 'Read-only' is the only minor redundancy with annotations.

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, single-project lookup with two well-documented parameters and no output schema, the description fully covers what the tool returns, how membership is determined, and how to use the results correctly. Nothing critical is missing.

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

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

Schema coverage is 100%, so the schema already documents project_id and include_email well. The description reinforces the assignee_id relationship but adds little parameter-level detail beyond what the schema provides, 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?

Opens with a specific verb and resource: 'Lists the people on this project with their ids.' It also clarifies the two possible membership sources (explicit members or task assignees), so an agent knows exactly what the tool returns and how it differs from the other get_project_* 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?

Clear context is given: use the returned id as assignee_id in create_task or update_task, never guess an id, and never assign work outside the returned set. It doesn't explicitly name alternatives or when-not-to-use cases, but no sibling tool competes for this purpose, so the guidance is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds valuable context beyond annotations by stating that this is 'instructions for you, not a job queued on our side' and by revealing domain-specific pitfalls encoded in the scripts, such as null meaning missing and write steps requiring prior approval.

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 somewhat long but each sentence earns its place: core purpose, how to use the result, design rationale, encoded pitfalls, and a pointer to list_skills. It is front-loaded with the most important information and has no filler, though it could be tightened slightly.

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 fully explains what is returned: the tools to call, order, what to inspect, and what to hand back. It also covers how to use the result, the read-only nature, and the initial lookup step, making it complete for an agent to invoke 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 baseline is 3. The description does not add parameter-specific meaning beyond the schema; it only mentions that list_skills should be called when names are unknown, which is usage guidance rather than parameter semantics.

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

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

The description states a specific verb and resource: 'Returns the full script of one workflow' and enumerates exactly what the script contains. It clearly distinguishes itself from sibling tools by emphasizing that this is an executable instruction set for the agent, not a data/document retrieval operation.

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

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

It gives clear context: the result is meant to be read and then run by the agent itself, and it explicitly directs the agent to call list_skills first when names are unknown. It does not enumerate explicit when-not-to-use cases, but the purpose and workflow are clear enough to guide selection.

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

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds context beyond annotations by clarifying accepted ID formats (LAB-42 or UUID) and warning against inefficient looping, which reflects real behavioral expectations.

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

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

Three sentences, each earning its place: the first states the return value, the second explains accepted identifiers, and the third gives usage guidance with a concrete alternative. Information is front-loaded and there is no filler.

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

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

For a simple read-by-id tool with two fully documented parameters and annotations covering safety, the description is complete. It tells the agent what it returns, how to identify the task, and when to prefer the sibling list_tasks, with no missing information needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents task_id and project_id. The description reinforces that task_id accepts a human id or UUID, but this largely duplicates the schema's own parameter description and adds nothing about project_id's optional-once behavior.

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

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

Description opens with a specific verb and resource: 'Returns one task in full', then enumerates the fields included (description, dates, assignee, labels, status, parent). It also distinguishes itself from list_tasks by noting it provides detail behind a single row.

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

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

The description explicitly states when to use the tool: 'when a row from list_tasks needs the detail behind it.' It also gives a clear when-not and alternative: 'Do not loop it over a whole backlog — filter with list_tasks instead, which is one call rather than fifty.'

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 readOnly, idempotent, non-destructive. The description adds context about what the aggregate covers (totals by status/type/priority plus overdue) and that it avoids paging, which is useful behavioral information. It doesn't disclose pagination or output format, but for a read-only aggregate that's minor.

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 sentences, each earning its place: scope, value proposition, clarification of scope, and routing to the alternative tool. Front-loaded with the main purpose.

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

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

Given single parameter, full schema coverage, and read-only annotations, the description explains what the tool returns at a high level. It doesn't specify the exact structure of the aggregates, but no output schema exists and the description names the groupings sufficiently for an agent to understand what it gets.

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

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

With 100% schema coverage and a single parameter, the schema fully documents project_id. The description reinforces that it's a single project and hints at omission to list projects, but the schema already states that. Baseline 3 plus slight value from clarifying scoping, thus 4.

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 ('Aggregate counts for one project'), enumerates the exact groupings (status, type, priority, overdue), and contrasts itself with list_tasks and get_project_structure, distinguishing it from 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?

Explicit when-to-use (answers 'how is this project doing' in one call) and when-not-to-use (for per-epic breakdowns, get_project_structure is the only tool), naming the alternative directly.

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

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

Beyond the readOnly/idempotent annotations, the description explains important behavior: planned counts leaf tasks with overlapping plans, worked counts time entries in the window, and null KPIs must not be treated as zero. This prevents a serious misinterpretation and is valuable behavioral context.

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

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

The description is three sentences with no filler: the first summarizes the report contents, the second clarifies counting and null semantics, and the third gives usage guidance. Each sentence earns its place and the most important details are front-loaded.

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

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

For a tool with no output schema, the description sufficiently explains the returned content, the meaning of KPIs, the time window, and null handling. It also provides sibling context and usage timing, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 50%; project_id is described in the schema, while periodDays is not. The description compensates by explaining periodDays' default, max, and window semantics, including how planned vs. worked counts relate to the window. It does not add much for project_id, but that is already covered.

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

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

The description clearly states what the tool produces: a time report with planned vs. logged hours, billable split, and divergence tasks. It is specific about the resource (project) and the time window, and the sibling references in the usage sentence help distinguish it from get_project_alerts and get_task_stats.

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 explicitly says when to use the tool ('when someone asks how a period went, before writing any status update') and names related tools for adjacent concerns: get_project_alerts for risk and get_task_stats for delivery. This gives an agent clear contextual guidance.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false. The description adds important behavioral context beyond those: it is 'cheap to call', returns paginated results with `total` and `has_more`, and issues an explicit warning not to treat page 1 as the whole Wiki when `has_more` is true. This is valuable operational detail not present in the annotations.

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

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

The description is dense and every sentence earns its place, covering purpose, cost, pagination, and guidance toward alternatives. It is slightly more verbose than strictly necessary, especially the 'page: 2, page: 3, and so on' portion, but it remains focused and front-loaded with the most important information.

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

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

For a simple list tool with no output schema, the description adequately covers what the response carries (`title`, `id`, `total`, `has_more`), how pagination works, and how the results are ordered. The safety profile is fully covered by annotations, and the guidance to siblings completes the picture. Nothing essential is missing for an agent to invoke 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 the schema already documents all three parameters. The description reinforces the `page` parameter's relationship to `has_more` and the pagination flow, but does not add substantial new meaning beyond what the input schema already provides. A baseline 3 is appropriate here.

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

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

The description clearly states the action ('Lists'), the resource ('this project's documents and Wiki pages'), and the specific output scope ('title and id only'). It also distinguishes this tool from siblings by noting the 'newest first' ordering and the fact that it is a lightweight listing operation.

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

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

The description explicitly says this is 'the right way to see what exists before reading anything', directly tells the agent when to prefer `search_documents` instead, and explains how to chain pagination with `page: 2`, `page: 3`, and so on. It also routes the caller to `get_document_full_content` after choosing an id, which is excellent alternate-tool 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?

Beyond the readOnlyHint and idempotentHint annotations, the description adds meaningful behavioral detail: 'Nothing executes on the FrameOn side, and asking for one costs you nothing but the text.' It also discloses the return shape: each entry carries a name, a one-line purpose, and the tools it uses.

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

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

The description is longer than minimal but front-loads the core purpose and keeps each paragraph purposeful. There is slight redundancy between 'Cheap to call' and 'costs you nothing but the text,' but it does not obscure the content.

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

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

With no output schema, the description explains what the returned entries contain and what to do next. It covers purpose, cost, output structure, side-effect behavior, and the follow-up call to get_skill, making the tool fully usable without additional context.

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

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

The tool has zero parameters and schema description coverage is 100%, so there are no parameter semantics to clarify. Per the baseline for zero-parameter tools, this is fully adequate.

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 ('Lists the ready-made workflows this workspace knows how to run') and enumerates concrete examples. It is clearly distinguished from the sibling get_skill by presenting listing as the precursor to fetching one skill.

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 context: 'worth calling once at the start of a session so you know what exists before improvising a sequence of calls.' It also points to get_skill as the next step, though it does not state an explicit when-not-to-use 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds substantial behavioral detail on top: pagination with limit capping at 100, has_more/next_page response fields, a warning against partial backlog reads, and the project_id omission side effect. No contradiction with annotations.

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

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

Three sentences with no filler: the first states the core function, the second delivers the pagination contract, and the third gives actionable usage guidance. The warning about reading only page 1 is stylized but earns its place by emphasizing a common failure mode.

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 paginated read tool with strong annotations, the description is nearly complete: it covers filters, pagination semantics, sequencing before other operations, and project_id fallback. It does not describe the shape of returned task items, but the absence of an output schema is partially mitigated by the disclosed pagination keys and schema-documented task types.

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 goes beyond the schema by clarifying the pagination boundary (limit caps at 100), the meaning of response pagination fields, and the special behavior of omitting project_id. It also summarizes the filter dimensions, adding real semantic value above the schema.

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

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

The description states a specific action ('Lists tasks in one project') with optional filters, making its purpose clear and distinguishable from sibling tools such as get_task (single task retrieval) and get_task_stats (aggregate statistics). It also frames downstream usage before create_task and update_task, reinforcing the tool's role.

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

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

The description gives explicit usage context: call this before create_task to find a parent, and before update_task when the id is unknown. It also adds a useful fallback behavior for omitting project_id to discover accessible projects. It does not explicitly name sibling alternatives or state when not to use this tool, so it falls just short of a 5.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds behavioral context beyond that: it returns 1–10 excerpts, defaults to 5, never returns whole pages, and matches meaning rather than keywords.

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

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

Three sentences with no filler: purpose first, then behavioral/return characteristics, then usage rules. Every sentence earns its place and the most decision-relevant guidance is front-loaded.

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

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

The description fully covers invocation behavior, result shape, and follow-up routing. It names the sibling to use for full content and the creation tool to avoid, making the tool self-sufficient even without an 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. The description adds value by explaining the query parameter's intended usage ('give it a question rather than a term'), which goes beyond the schema's generic 'Termo ou pergunta' description.

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

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

States a specific verb and resource: semantic search over Wiki pages and uploaded documents. It distinguishes itself from siblings by emphasizing meaning-matching rather than keyword matching, and by noting it returns excerpts rather than full pages.

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 instructs the agent to phrase queries as questions rather than keywords, to follow up with get_document_full_content when an excerpt looks right, and to always search before create_wiki_page to avoid duplicating team memory. This gives clear when-to-use and follow-up guidance.

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