[mabry1985]

Why

protoAgent sends every bound tool's JSON schema on every model call. A fleet audit put jobCoach's fixed overhead at ~113k tokens/call, mostly schemas; agents with github.write: true bind all 38 github tools (~33k schema chars).

What

• Text only. Every github_* @tool docstring is now one terse paragraph: what it does, when to use it vs siblings, and the hard call-time constraints. No tool renamed; no parameter renamed / removed / reordered; types, defaults and required-ness unchanged.
• Kept (each said once): merge confirm=true + dry_run + full-sha head guard (+ not with delete_branch), squash-subject trap, subject/body refused on rebase; the issue body gate sections + kind/label coupling + "search first, no duplicate"; review approve/request-changes guards (CI running / unreadable / own PR) and the evidence rule; confirm on dispatch / tag / edit-release / upload-asset with why; tag-never-moved; create-label never overwrites; the 20000-char read cap, LINE-boundary cut and continue with start_line= paging footer; github_path_exists EXISTS / MISSING / Gap semantics; "Call github_status FIRST" on errors.
• De-duplicated: the per-tool "Repository as owner/name. Omit to use the agent's configured default repo." line (38×) is said once in github_status (always registered) and in the skill; the Args:/Returns: blocks are folded into prose; the docstrings' 8-space continuation indentation (which shipped verbatim in the description) is gone.
• New skills/github/SKILL.md (the host auto-loads a plugin's skills/ dir): the workflow manual that used to live in descriptions — PR review order, fix-round thread replies, CI triage, filing, merging, the release sequence (dispatch → run_jobs → tag → release → notes/assets), the paging footer shapes.
• PROTO.md: notes the skill and a rule that descriptions stay terse.

Measured

Serialized OpenAI tool schema chars (convert_to_openai_tool, host-free testkit, github.write: true):

Tool	Before	After	Δ
github_merge_pr	1,941	962	-50%
github_create_issue	1,646	883	-46%
github_read_pr_file	1,625	755	-54%
github_read_file	1,512	843	-44%
github_create_tag	1,207	740	-39%
github_path_exists	1,120	644	-43%
github_dispatch_workflow	1,106	650	-41%
github_get_pr	1,050	629	-40%
github_create_label	1,039	428	-59%
github_upload_release_asset	1,013	601	-41%
github_reply_thread	1,002	513	-49%
github_review_threads	898	567	-37%
github_search_issues	882	556	-37%
github_review_request_changes	871	533	-39%
github_edit_pr	870	466	-46%
github_review_approve	815	469	-42%
github_close	805	452	-44%
github_resolve_thread	803	467	-42%
github_run_jobs	796	468	-41%
github_set_assignees	765	426	-44%
github_issue_comments	744	410	-45%
github_set_labels	744	469	-37%
github_review_comment	732	425	-42%
github_get_issue	727	443	-39%
github_edit_issue	711	389	-45%
github_release	686	413	-40%
github_list_prs	675	420	-38%
github_create_pr	670	365	-46%
github_edit_release	669	403	-40%
github_release_asset	624	365	-42%
github_ci_runs	615	371	-40%
github_run_failure	597	389	-35%
github_repo_contents	569	328	-42%
github_status	565	475	-16%
github_comment	565	301	-47%
github_pr_diff	564	337	-40%
github_get_commit_diff	542	336	-38%
github_list_issues	522	305	-42%
all 38	33,287	18,996	-42.9%
read-only 19 (write: false)	15,313	9,054	-40.9%

Tests

ruff check . && ruff format --check . && pytest -q — 509 passed. The description-pinning tests (capped at 20000 chars, LINE boundary, continue with start_line=, DEDUPE BEFORE FILING, duplicate) pass unchanged.

No version bump (no release in this PR).

🤖 Generated with Claude Code

[protoreview]

QA panel review — PASS

code-review-structural · head fc7c8526180f · formal

No findings were raised, so there was nothing to verify. The panel confirmed this is a clean docstring-compression refactor: all four LLM finders independently verified that hard call-time constraints (caps, guards, cross-references, refusal semantics) are preserved in the compressed text, and the docstring-pinning tests remain green. The protoPatch engine flagged three pre-existing code-logic issues, but none fall within this PR's diff and were correctly dropped per scope. No defects in the diff itself.

No findings — the review came back clean.

findings JSON (machine-readable)

[]

[protoreview]

Promoting the PASS verdict for head fc7c8526180f: all checks terminal-green, zero unresolved review threads. (approve-on-green)