Enhancement: Simplify twprojects tool descriptions

docs/glossary.md

@@ -0,0 +1,285 @@
+# Teamwork.com Glossary
+
+Definitions of the core entities exposed by the Teamwork MCP server. Useful as
+context for skills, prompts, or onboarding documentation. Tool descriptions in
+the MCP server itself are intentionally terse — drop any of these blurbs into a
+system prompt or skill if a richer entity definition is needed.
+
+Entries are listed alphabetically.
+
+## Activity
+
+Activity is a record of actions and updates that occur across your projects,
+tasks, and communications, giving you a clear view of what's happening within
+your workspace. Activities capture changes such as task completions, activities
+added, files uploaded, or milestones updated, and present them in a
+chronological feed so teams can stay aligned without needing to check each
+individual project or task. This stream of information helps improve
+transparency, ensures accountability, and keeps everyone aware of progress and
+decisions as they happen.
+
+## Comment
+
+In the Teamwork.com context, a comment is a way for users to communicate and
+collaborate directly within tasks, milestones, files, or other project items.
+Comments allow team members to provide updates, ask questions, give feedback,
+or share relevant information in a centralized and contextual manner. They
+support rich text formatting, file attachments, and @mentions to notify
+specific users or teams, helping keep discussions organized and easily
+accessible within the project. Comments are visible to all users with access
+to the item, promoting transparency and keeping everyone aligned.
+
+## Company (Client)
+
+In the context of Teamwork.com, a company represents an organization or
+business entity that can be associated with users, projects, and tasks within
+the platform, and it is often referred to as a "client." It serves as a way to
+group related users and projects under a single organizational umbrella,
+making it easier to manage permissions, assign responsibilities, and organize
+work. Companies (or clients) are frequently used to distinguish between
+internal teams and external collaborators, enabling teams to work efficiently
+while maintaining clear boundaries around ownership, visibility, and access
+levels across different projects.
+
+## Industry
+
+Industry refers to the business sector or market category that a company
+belongs to, such as technology, healthcare, finance, or education. It helps
+provide context about the nature of a company's work and can be used to better
+organize and filter data across the platform. By associating companies and
+projects with specific industries, Teamwork.com allows teams to gain clearer
+insights, tailor communication, and segment information in ways that make it
+easier to manage relationships and understand the broader business landscape
+in which their clients and partners operate.
+
+## Job role
+
+Job role defines a user's primary function or position within the
+organization, such as developer, designer, project manager, or account
+manager. It provides high-level context about what a person is generally
+responsible for, helping teams understand who does what across projects and
+departments. Job roles are commonly used in resource planning, capacity
+forecasting, and reporting, allowing managers to group work by role, plan
+future demand more accurately, and ensure the right mix of roles is available
+to deliver projects efficiently.
+
+## Link
+
+In the context of Teamwork.com, a link is a saved URL attached to a project,
+task, or other item, allowing users to quickly reference and access external
+resources (such as documents, tools, or websites) directly within their
+workflow.
+
+## Message
+
+In the context of Teamwork.com, a message is a structured communication post
+within a project that allows team members to share updates, discuss topics,
+and document decisions in a centralized, threaded format. It includes a title,
+a detailed message body, and replies from collaborators, all tied to the
+project for clear context and visibility, making it ideal for important
+discussions that need to be organized and easily referenced over time.
+
+## Message reply
+
+In the context of Teamwork.com, a message reply is a response within a project
+message thread that allows team members to contribute to the discussion, ask
+questions, or provide updates while keeping all communication organized under
+the original message. Replies maintain context by staying linked to the main
+topic, include the author and timestamp, and help create a clear, ongoing
+conversation that is easy for everyone involved to follow and reference.
+
+## Milestone
+
+In the context of Teamwork.com, a milestone represents a significant point or
+goal within a project that marks the completion of a major phase or a key
+deliverable. It acts as a high-level indicator of progress, helping teams
+track whether work is advancing according to plan. Milestones are typically
+used to coordinate efforts across different tasks and task lists, providing a
+clear deadline or objective that multiple team members or departments can
+align around. They don't contain individual tasks themselves but serve as
+checkpoints to ensure the project is moving in the right direction.
+
+## Notebook
+
+Notebook is a space where teams can create, share, and organize written
+content in a structured way. It's commonly used for documenting processes,
+storing meeting notes, capturing research, or drafting ideas that need to be
+revisited and refined over time. Unlike quick messages or task comments,
+notebooks provide a more permanent and organized format that can be easily
+searched and referenced, helping teams maintain a centralized source of
+knowledge and ensuring important information remains accessible to everyone
+who needs it.
+
+## Project
+
+The project feature in Teamwork.com serves as the central workspace for
+organizing and managing a specific piece of work or initiative. Each project
+provides a dedicated area where teams can plan tasks, assign responsibilities,
+set deadlines, and track progress toward shared goals. Projects include tools
+for communication, file sharing, milestones, and time tracking, allowing teams
+to stay aligned and informed throughout the entire lifecycle of the work.
+Whether it's a product launch, client engagement, or internal initiative,
+projects in Teamwork.com help teams structure their efforts, collaborate more
+effectively, and deliver results with greater visibility and accountability.
+
+## Project budget
+
+In the context of Teamwork.com, a project budget defines the overall budget
+allocation for a project, including capacity and usage tracking over time. It
+can be scoped by status and project, enabling teams to monitor financial or
+effort limits, track consumption, and understand budget performance across
+active, upcoming, and completed budget periods.
+
+## Project category
+
+The project category is a way to group and label related projects so teams can
+organize their work more clearly across the platform. By assigning a category,
+you create a higher-level structure that makes it easier to filter, report
+on, and navigate multiple projects, ensuring that departments, workflows, or
+strategic areas remain neatly aligned and easier to manage.
+
+## Project member
+
+In the context of Teamwork.com, a project member is a user who is assigned to
+a specific project. Project members can have different roles and permissions
+within the project, allowing them to collaborate on tasks, view project
+details, and contribute to the project's success. Managing project members
+effectively is crucial for ensuring that the right people are involved in the
+right tasks, and it helps maintain accountability and clarity throughout the
+project's lifecycle.
+
+## Project template
+
+The project template is a reusable project structure designed to standardize
+workflows and streamline project setup. It typically includes predefined
+tasks, task lists, milestones, and timelines that reflect a repeatable
+process, allowing teams to quickly spin up new projects with consistent
+organization, clear responsibilities, and efficient execution from the start.
+
+## Search
+
+Search is a feature that allows users to quickly find projects, tasks, files,
+messages, and other items across their workspace by entering keywords, helping
+them locate information and navigate their work efficiently from a single
+place.
+
+## Skill
+
+Skill represents a specific capability, area of expertise, or proficiency that
+can be assigned to users to describe what they are good at or qualified to
+work on. Skills help teams understand the strengths available across the
+organization and make it easier to match the right skills to the right work
+when planning projects, assigning tasks, or managing resources. By associating
+skills with users and leveraging them in planning and reporting, Teamwork
+enables more effective workload distribution, better project outcomes, and
+clearer visibility into whether the team has the capabilities needed to
+deliver upcoming work.
+
+## Tag
+
+In the context of Teamwork.com, a tag is a customizable label that can be
+applied to various items such as tasks, projects, milestones, messages, and
+more, to help categorize and organize work efficiently. Tags provide a
+flexible way to filter, search, and group related items across the platform,
+making it easier for teams to manage complex workflows, highlight priorities,
+or track themes and statuses. Since tags are user-defined, they adapt to each
+team's specific needs and can be color-coded for better visual clarity.
+
+## Task
+
+In Teamwork.com, a task represents an individual unit of work assigned to one
+or more team members within a project. Each task can include details such as
+a title, description, priority, estimated time, assignees, and due date,
+along with the ability to attach files, leave comments, track time, and set
+dependencies on other tasks. Tasks are organized within task lists, helping
+structure and sequence work logically. They serve as the building blocks of
+project management in Teamwork, allowing teams to collaborate, monitor
+progress, and ensure accountability throughout the project's lifecycle.
+
+## Tasklist
+
+In the context of Teamwork.com, a task list is a way to group related tasks
+within a project, helping teams organize their work into meaningful sections
+such as phases, categories, or deliverables. Each task list belongs to a
+specific project and can include multiple tasks that are typically aligned
+with a common goal. Task lists can be associated with milestones, and they
+support privacy settings that control who can view or interact with the tasks
+they contain. This structure helps teams manage progress, assign
+responsibilities, and maintain clarity across complex projects.
+
+## Tasklist budget
+
+In the context of Teamwork.com, a tasklist budget is a budget allocation
+attached to a specific task list within a project budget. It tracks capacity
+(in time or money) assigned to and consumed by a task list, helping teams
+monitor spend and effort at a granular level within a broader project budget.
+
+## Team
+
+In the context of Teamwork.com, a team is a group of users who are organized
+together to collaborate more efficiently on projects and tasks. Teams help
+structure work by grouping individuals with similar roles, responsibilities,
+or departmental functions, making it easier to assign work, track progress,
+and manage communication. By using teams, organizations can streamline
+project planning and ensure the right people are involved in the right parts
+of a project, enhancing clarity and accountability across the platform.
+
+## Timelog
+
+Timelog refers to a recorded entry that tracks the amount of time a person has
+spent working on a specific task, project, or piece of work. These entries
+typically include details such as the duration of time worked, the date and
+time it was logged, who logged it, and any optional notes describing what was
+done during that period. Timelogs are essential for understanding how time is
+being allocated across projects, enabling teams to manage resources more
+effectively, invoice clients accurately, and assess productivity. They can be
+created manually or with timers, and are often used for reporting and billing
+purposes.
+
+## Timer
+
+Timer is a built-in tool that allows users to accurately track the time they
+spend working on specific tasks, projects, or client work. Instead of manually
+recording hours, users can start, pause, and stop timers directly within the
+platform or through the desktop and mobile apps, ensuring precise time logs
+without interrupting their workflow. Once recorded, these entries are
+automatically linked to the relevant task or project, making it easier to
+monitor productivity, manage billable hours, and generate detailed reports for
+both internal tracking and client invoicing.
+
+## User
+
+A user is an individual who has access to one or more projects within a
+Teamwork site, typically as a team member, collaborator, or administrator.
+Users can be assigned tasks, participate in discussions, log time, share
+files, and interact with other members depending on their permission levels.
+Each user has a unique profile that defines their role, visibility, and
+access to features and project data. Users can belong to clients/companies or
+teams within the system, and their permissions can be customized to control
+what actions they can perform or what information they can see.
+
+## Workflow
+
+A workflow is a configurable process template in Teamwork.com that defines a
+series of stages through which tasks progress. Workflows help teams
+standardize their processes, automate stage transitions, and maintain
+consistency across projects by providing a structured path from start to
+completion.
+
+## Workflow stage
+
+A workflow stage is a single step within a workflow in Teamwork.com. Stages
+are ordered and define the progression path for tasks as they move through
+the workflow from start to completion. Each stage belongs to a parent
+workflow.
+
+## Workload
+
+Workload is a visual representation of how tasks are distributed across team
+members, helping you understand who is overloaded, who has capacity, and how
+work is balanced within a project or across multiple projects. It takes into
+account assigned tasks, due dates, estimated time, and working hours to give
+managers and teams a clear picture of availability and resource allocation.
+By providing this insight, workload makes it easier to plan effectively,
+prevent burnout, and ensure that deadlines are met without placing too much
+pressure on any single person.

internal/twprojects/activities.go

@@ -21,13 +21,6 @@ const (
 	MethodActivityList toolsets.Method = "twprojects-list_activities"
 )
 
-const activityDescription = "Activity is a record of actions and updates that occur across your projects, tasks, and " +
-	"communications, giving you a clear view of what’s happening within your workspace. Activities capture changes " +
-	"such as task completions, activities added, files uploaded, or milestones updated, and present them in a " +
-	"chronological feed so teams can stay aligned without needing to check each individual project or task. This " +
-	"stream of information helps improve transparency, ensures accountability, and keeps everyone aware of progress " +
-	"and decisions as they happen."
-
 var (
 	activityListOutputSchema *jsonschema.Schema
 )
@@ -47,9 +40,8 @@ func init() {
 func ActivityList(engine *twapi.Engine) toolsets.ToolWrapper {
 	return toolsets.ToolWrapper{
 		Tool: &mcp.Tool{
-			Name: string(MethodActivityList),
-			Description: "List activities in Teamwork.com. Provide project_id to scope to a specific project. " +
-				activityDescription,
+			Name:        string(MethodActivityList),
+			Description: "List recent activity events. Scope by project_id or omit for site-wide.",
 			Annotations: &mcp.ToolAnnotations{
 				Title:        "List Activities",
 				ReadOnlyHint: true,

internal/twprojects/budgets.go

@@ -22,16 +22,6 @@ const (
 	MethodProjectBudgetList  toolsets.Method = "twprojects-list_project_budgets"
 )
 
-const tasklistBudgetDescription = "In the context of Teamwork.com, a tasklist budget is a budget allocation " +
-	"attached to a specific task list within a project budget. It tracks capacity (in time or money) assigned to " +
-	"and consumed by a task list, helping teams monitor spend and effort at a granular level within a broader " +
-	"project budget."
-
-const projectBudgetDescription = "In the context of Teamwork.com, a project budget defines the overall budget " +
-	"allocation for a project, including capacity and usage tracking over time. It can be scoped by status and " +
-	"project, enabling teams to monitor financial or effort limits, track consumption, and understand budget " +
-	"performance across active, upcoming, and completed budget periods."
-
 var (
 	tasklistBudgetListOutputSchema *jsonschema.Schema
 	projectBudgetListOutputSchema  *jsonschema.Schema
@@ -59,7 +49,7 @@ func ProjectBudgetList(engine *twapi.Engine) toolsets.ToolWrapper {
 	return toolsets.ToolWrapper{
 		Tool: &mcp.Tool{
 			Name:        string(MethodProjectBudgetList),
-			Description: "List project budgets in Teamwork.com. " + projectBudgetDescription,
+			Description: "List project-level budgets.",
 			Annotations: &mcp.ToolAnnotations{
 				Title:        "List Project Budgets",
 				ReadOnlyHint: true,
@@ -159,7 +149,7 @@ func TasklistBudgetList(engine *twapi.Engine) toolsets.ToolWrapper {
 	return toolsets.ToolWrapper{
 		Tool: &mcp.Tool{
 			Name:        string(MethodTasklistBudgetList),
-			Description: "List tasklist budgets for a project budget in Teamwork.com. " + tasklistBudgetDescription,
+			Description: "List tasklist-level budgets for a project budget.",
 			Annotations: &mcp.ToolAnnotations{
 				Title:        "List Tasklist Budgets",
 				ReadOnlyHint: true,